On Jun 14, 2011, at 05:53 PM, Zygmunt Krynicki wrote:
>Can please we have standardized hooks to build sphinx documentation and run
>setup.py test tests?
I'd like to see the packaging folks address this. Eric is subscribed to this
list and can probably speak to packaging's take on it, but my preferences
would be that
$ pysetup test
would run all the tests in Python 3.3 and beyond (and in a distutils2 world).
I don't think this is supported (yet?), and my limited testing required some
2to3 hackery that isn't quite working. In Python < 3.3, using
setuptools/distribute/distutils2, this should be the standard interface:
$ python setup.py test
and in fact that works quite well, even with 2to3 integration. You need to
add:
test_suite='path.to.testdir'
in your setup() call, and possibly a `convert_2to3_doctests` key as well (this
is the part that does not work for me in Python 3.3).
>Can those hooks do the right thing with generated documentation (dealing all
>the boring .doc-base files, replacing jquery with symlinks, ensuring proper
>requirements are used).
Documentation and Sphinx integration is trickier because while Sphinx is the
de-facto standard for Python documentation, it is a separate project from core
Python, and I know of no initiatives to pull it into the core (nor, IMO should
there be).
In a setup.py world:
$ python setup.py build_sphinx
is the standard for creating the HTML from rST files, and again, this works
well for me in Python 2. I might quibble with the command name, since I
always get it wrong (sphinx_build ;). Of course, you need Sphinx installed, a
proper conf.py file, and this bit in your setup.cfg:
[build_sphinx]
source_dir: path/to/root.rst
This upstream Sphinx bug addresses jquery compatiblity:
http://tinyurl.com/3rg3r7b
Georg (the upstream Sphinx maintainer) makes a good point, which is that he
really can't be expected to test Sphinx with any version of jquery than the
one he ships. Operating systems (Debian/Ubuntu) are the integrators, and as
Jakub points out in that issue, if Debian deviates from upstream by replacing
Sphinx's version of jquery, it's incumbent on Debian to ensure it works
properly.
Cheers,
-Barry
Attachment:
signature.asc
Description: PGP signature