diff --git a/EXAMPLES b/EXAMPLES index 62c978425..38dec13f4 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -128,6 +128,7 @@ Documentation using another builtin theme * Distribute: http://packages.python.org/distribute/ (nature) * Jinja: http://jinja.pocoo.org/ (scrolls) * jsFiddle: http://doc.jsfiddle.net/ (nature) +* libLAS: http://liblas.org/ (nature) * MPipe: http://vmlaker.github.io/mpipe/ (sphinx13) * pip: http://pip.openplans.org/ (nature) * Programmieren mit PyGTK und Glade (German): @@ -137,7 +138,7 @@ Documentation using another builtin theme * sqlparse: http://python-sqlparse.googlecode.com/svn/docs/api/index.html (agogo) * Sylli: http://sylli.sourceforge.net/ (nature) -* libLAS: http://liblas.org/ (nature) +* Tuleap Open ALM: https://tuleap.net/doc/en/ (nature) * Valence: http://docs.valence.desire2learn.com/ (haiku) @@ -146,6 +147,7 @@ Documentation using a custom theme/integrated in a site * Blender: http://www.blender.org/documentation/250PythonDoc/ * Blinker: http://discorporate.us/projects/Blinker/docs/ +* Ceph: http://ceph.com/docs/master/ * Classy: http://classy.pocoo.org/ * DEAP: http://deap.gel.ulaval.ca/doc/0.8/index.html * Django: http://docs.djangoproject.com/ @@ -194,6 +196,7 @@ Homepages and other non-documentation sites * lunarsite: http://lunaryorn.de/ * Red Hot Chili Python: http://redhotchilipython.com/ * The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/ +* Uni. Berkeley Advanced Control Systems course: http://www.me.berkeley.edu/ME233/sp14/ * VOR: http://www.vor-cycling.be/ diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 38d7700e3..4f2e9d969 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -19,6 +19,15 @@ documentation from docstrings in a semi-automatic way. package must be in one of the directories on :data:`sys.path` -- adapt your :data:`sys.path` in the configuration file accordingly. +.. warning:: + + :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any + modules have side effects on import, these will be executed by ``autodoc`` + when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their main + routine is protected by a ``if __name__ == '__main__'`` condition. + For this to work, the docstrings must of course be written in correct reStructuredText. You can then use all of the usual Sphinx markup in the docstrings, and it will end up correctly in the documentation. Together with diff --git a/doc/invocation.rst b/doc/invocation.rst index dca02793a..37718fe8c 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -247,6 +247,16 @@ where *packagedir* is the path to the package to document, and *outputdir* is the directory where the generated sources are placed. Any *pathnames* given are paths to be excluded ignored during generation. +.. warning:: + + ``sphinx-apidoc`` generates reST files that use :mod:`sphinx.ext.autodoc` to + document all found modules. If any modules have side effects on import, + these will be executed by ``autodoc`` when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their main + routine is protected by a ``if __name__ == '__main__'`` condition. + + The :program:`sphinx-apidoc` script has several options: .. program:: sphinx-apidoc diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst index f00e29d87..a01d2a82f 100644 --- a/doc/man/sphinx-apidoc.rst +++ b/doc/man/sphinx-apidoc.rst @@ -19,21 +19,33 @@ other automatic API documentation tools. *sourcedir* must point to a Python package. Any *pathnames* given are paths to be excluded from the generation. +.. warning:: + + ``sphinx-apidoc`` generates source files that use :mod:`sphinx.ext.autodoc` + to document all found modules. If any modules have side effects on import, + these will be executed by ``autodoc`` when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their main + routine is protected by a ``if __name__ == '__main__'`` condition. + Options ------- --o Directory to place the output files. If it does not exist, - it is created. --f, --force Usually, apidoc does not overwrite files, unless this option - is given. --n, --dry-run If given, apidoc does not create any files. --s Suffix for the source files generated, default is ``rst``. --d Maximum depth for the generated table of contents file. --T, --no-toc Do not create a table of contents file. --F, --full If given, a full Sphinx project is generated (``conf.py``, - ``Makefile`` etc.) using sphinx-quickstart. --E, --separate Put each module file in its own page. +-o Directory to place the output files. If it does not exist, + it is created. +-f, --force Usually, apidoc does not overwrite files, unless this option + is given. +-l, --follow-links Follow symbolic links. +-n, --dry-run If given, apidoc does not create any files. +-s Suffix for the source files generated, default is ``rst``. +-d Maximum depth for the generated table of contents file. +-T, --no-toc Do not create a table of contents file. +-F, --full If given, a full Sphinx project is generated (``conf.py``, + ``Makefile`` etc.) using sphinx-quickstart. +-e, --separate Put each module file in its own page. +-E, --no-headings Don't create headings for the modules/packages +-P, --private Include "_private" modules These options are used with ``-F``: diff --git a/doc/tutorial.rst b/doc/tutorial.rst index 8e949d4c5..cae4c8db1 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -245,6 +245,15 @@ autodoc needs to import your modules in order to extract the docstrings. Therefore, you must add the appropriate path to :py:data:`sys.path` in your :file:`conf.py`. +.. warning:: + + :mod:`~sphinx.ext.autodoc` **imports** the modules to be documented. If any + modules have side effects on import, these will be executed by ``autodoc`` + when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their main + routine is protected by a ``if __name__ == '__main__'`` condition. + |more| See :mod:`sphinx.ext.autodoc` for the complete description of the features of autodoc.