Add warnings that autodoc imports the modules.

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/invocation.rst b/doc/invocation.rst
index 338728b6..654921be 100644
--- a/doc/invocation.rst
+++ b/doc/invocation.rst
@@ -238,6 +238,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