no docs package / html docs

We originally decided not to package the docs, as generating them ends up requiring some fairly obscure packages, and we didn't want to force everyone building ceph to install all of them. Some things like sphinx-ditaa and asphyxiate were created from scratch, so they're not even packaged currently.

Got it, but the build prereqs for docs are not needed after they've been generated. I transfered them to a system with none of that stuff and they can be read in a browser or via local server just fine.

Once generated, the html docs can go into /usr/share/doc/ceph-doc from a similarly named package.

I can perhaps add a separate Makefile & debian under doc to build a package for this if you are interested (via github & cephs contrib guildlines).

I think if we package them at all, they should probably be in the regular debian directory so that they get built along with regular releases... otherwise it will be a lot of additional work to build and publish the packages. The rules or Makefile would probably need to do things like clone sphinx-ditaa.git from github etc in order to do the build. As long as the Build-Requires: is sufficient I guess it's okay to do that...

I must agree w/ Tv that keeping the docs build separate helps source users who don't need to deal with all that. Many other projects actually do that ('cd doc; make html') due to substantial additional build deps., and I think I can take some cues from that.

The top Makefile could just include an optional target to descend into doc and build that package, and the separate 'debian' there can be largely or entirely generated from the top level (e.g. symlinked as much as possible).

I'll put something together in a github clone you can look at (later this week).

just an update: Tv was right about the use of virtualenv: sphinx has to be *built* in the presence of sphinx-ditaa and asphyxiate, not taken from an installed system package. The burden on virtualenv can still be minimised if all other deps are installed [from platform repos (ubuntu)], but not python-sphinx. It still makes for a noticeably leaner and faster docs build.

I shall revisit how/where to shoehorn that in without disrupting things.

Subsequently, getting a docs package to build will be detached from the main build/packages while making use of the same debian resources as much as possible (likely with symlinks), so I'm still _not_ going to force docs to be built and/or packaged along with the main build.

Comment #6 is incorrect, you don't need to install Sphinx in the virtualenv, you just need to have the virtualenv active (so the extensions can be found).

Here's one way to achieve that:

PYTHONPATH=`pwd`/../src/pybind ./virtualenv/bin/python /usr/bin/sphinx-build -a -b dirhtml -d doctrees ../doc output/html

if it's a question of weather to install sphinx or kludge the use of it from system packages, I'd say whichever is less likely to break at some point later.

Otherwise; number one goal is Make Tv Happy.

This might be more to the specs Tv offered:

  https://github.com/seanchannel/ceph/commit/08f13c95bf210f433636d00d76b725feee6d3a37

. took out --quiet so you can see what is going into venv,
. check for path to sphinx-build
. added explicit call to venv python

Sage, thank you much for your comment (#4). Tv, thanks for guidance and letting me play along.

The ceph build already separates the main build from docs, and the requirements for building are already quite substantial, so if someone is up to the task of building deb packages on their own then they're up to dealing with the docs. I speculate it may be worth investigating if there are more current alternatives to the custom mods required for sphinx if that is the only roadblock.

Far be it for me to say that you must ship docs, however, it may be preferable to drive that traffic through the web site, which has the advantage of incorporating community updates more frequently, and I totally support that idea.

Since you don't really want another makefile and don't need another script to build docs, I suggest adding it to the main package build if they're going to ship at all, or let's close this issue and stick with the web site.

I count only two truly great solutions in any category that exist right now, and one is ceph. You have my allegiance.