merge with stable

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/
 
 

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

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

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 <outputdir>  Directory to place the output files.  If it does not exist,
+-o <outputdir>      Directory to place the output files.  If it does not exist,
-                it is created.
+                    it is created.
--f, --force     Usually, apidoc does not overwrite files, unless this option
+-f, --force         Usually, apidoc does not overwrite files, unless this option
-                is given.
+                    is given.
--n, --dry-run   If given, apidoc does not create any files.
+-l, --follow-links  Follow symbolic links.
--s <suffix>     Suffix for the source files generated, default is ``rst``.
+-n, --dry-run       If given, apidoc does not create any files.
--d <maxdepth>   Maximum depth for the generated table of contents file.
+-s <suffix>         Suffix for the source files generated, default is ``rst``.
--T, --no-toc    Do not create a table of contents file.
+-d <maxdepth>       Maximum depth for the generated table of contents file.
--F, --full      If given, a full Sphinx project is generated (``conf.py``,
+-T, --no-toc        Do not create a table of contents file.
-                ``Makefile`` etc.) using sphinx-quickstart.
+-F, --full          If given, a full Sphinx project is generated (``conf.py``,
--E, --separate  Put each module file in its own page.
+                    ``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``:
 

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.