RE : Bits from the Sphinx maintainer

[PICCA Frédéric-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr>]

> In python-sphinx 1.0.7+dfsg-1 I made a few important changes:

> 3) There is a new helper tool, dh_sphinxdoc, which helps with packaging
> Sphinx-generated documentation. More specifically:
> - it does a few sanity checks (e.g. for missing files that are
> needed for the JavaScript to work);
> - it replaces known *.js files with symlinks to files to
> /usr/share/javascript/sphinxdoc/ and generates ${sphinxdoc:Depends}
> substitution variable;
> - removes some cruft (.doctree/, .buildinfo).

Thanks for this it will ease at least my life a lot.

could you add in the man page the thinks to do to migrate a package to use this
helper, the same way it was done for dh_python2.

> If your package builds documentation using Sphinx, I highly recommend
> you to stop creating jquery.js symlink with dh_link (or such) and use
> dh_sphinxdoc instead. This is the only future-proof way to have
> fully-functional, policy compliant package with Sphinx-built
> documentation.

I tryed it for one of my package.
I faced this "issue".
the setup.py file of the upstream was generating the doc during the build process and install
it under the build/lib.xxx

so at the end all the documentation was under /usr/share/pyshare/<module>/doc/...

As dh_sphinxdoc is called before dh_python2, It could not find the documentation in the package.

so my question is

what is the right way to integrate sphinx generation doc in the build process using setup.py

that way I should propose this to the upstream and keep my dh script as simple as possible.

dh $@ --with python2 --with sphinxdoc

thanks

Frederic