vendredi 11 septembre 2015

How to deliberately fail a Sphinx build when autodoc fails an import

I have a CI (Jenkins) job which builds Sphinx documentation for my Python project:

#!/bin/bash
set -x
virtualenv $WORKSPACE
source $WORKSPACE/bin/activate
pip install 'sphinx>=1.3.1'
python setup.py build_sphinx

My project uses the Sphinx autodoc extension to extract docstrings from my modules by importing them, e.g. in "docs/api/foo.bar.rst":

.. automodule:: foo.bar
    :members:
    :undoc-members:
    :show-inheritance:

Now, if autodoc fails to import foo.bar, the Sphinx build shows the traceback in the logs and carries on building anyway, although it warns me that:

WARNING: toctree contains reference to document u'api/foo.bar' that doesn't have a title: no link will be generated

This results in missing documentation, so I'd like to make my Sphinx build step fail in this event. Is there a more elegant way of doing this than trying to grep the logs from build_sphinx?



via Chebli Mohamed

Aucun commentaire:

Enregistrer un commentaire