no docs package / html docs

Bug #1056103 reported by Sean Channel
This bug affects 1 person
Affects Status Importance Assigned to Milestone
ceph (Ubuntu)

Bug Description

Please add a package for the very nice Sphinx based html docs

James Page (james-page)
Changed in ceph (Ubuntu):
importance: Undecided → Low
importance: Low → Wishlist
status: New → Triaged
Revision history for this message
Tv (tv42) wrote :

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.

Revision history for this message
Sean Channel (sean-channel) wrote :

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.

Revision history for this message
Sean Channel (sean-channel) wrote :

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).

Revision history for this message
Sage Weil (sage-newdream) wrote :

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...

Revision history for this message
Sean Channel (sean-channel) wrote :

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).

Revision history for this message
Sean Channel (sean-channel) wrote :

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.

Revision history for this message
Tv (tv42) wrote :

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

Revision history for this message
Sean Channel (sean-channel) wrote :

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.

Revision history for this message
Sean Channel (sean-channel) wrote :

This might be more to the specs Tv offered:

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

Revision history for this message
Sean Channel (sean-channel) wrote :

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.

To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.