DOC: Move setup and usage of autodoc from "Getting Started" into the …

…extension docs

doc/usage/extensions/autodoc.rst

@@ -36,9 +36,21 @@ docstrings to correct reStructuredText before :mod:`autodoc` processes them.
 .. _Google: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
 .. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
 
+Getting started
+---------------
+
+Setup
+.....
+Activate the plugin by adding ``'sphinx.ext.autodoc'`` to the :confval:`extensions`
+in your :file:`conf.py`::
+
+   extensions = [
+       ...
+       'sphinx.ext.autodoc',
+   ]
 
 Ensuring the code can be imported
----------------------------------
+.................................
 
 :mod:`~sphinx.ext.autodoc` analyses the code and docstrings by introspection after
 importing the modules. For importing to work. you have to make sure that your
@@ -69,6 +81,23 @@ There are two ways to ensure this:
    - To cope with missing dependencies, specify the missing modules in
      :confval:`autodoc_mock_imports`.
 
+Usage
+.....
+
+You can now use the :ref:`autodoc-directives` to add formatted documentation for Python
+code elements like functions, classes, modules, etc. For example, to document the
+function ``io.open()``, reading its signature and docstring from the source file, you'd
+write ::
+
+   .. autofunction:: io.open
+
+You can also document whole classes or even modules automatically, using member
+options for the auto directives, like ::
+
+   .. automodule:: io
+      :members:
+
+.. _autodoc-directives:
 
 Directives
 ----------

doc/usage/quickstart.rst

@@ -259,43 +259,9 @@ source files, in documentation strings.  Sphinx supports the inclusion of
 docstrings from your modules with an :dfn:`extension` (an extension is a Python
 module that provides additional features for Sphinx projects) called *autodoc*.
 
-In order to use *autodoc*, you need to activate it in :file:`conf.py` by
-putting the string ``'sphinx.ext.autodoc'`` into the list assigned to the
-:confval:`extensions` config value::
-
-   extensions = ['sphinx.ext.autodoc']
-
-Then, you have a few additional directives at your disposal.  For example, to
-document the function ``io.open()``, reading its signature and
-docstring from the source file, you'd write this::
-
-   .. autofunction:: io.open
-
-You can also document whole classes or even modules automatically, using member
-options for the auto directives, like ::
-
-   .. automodule:: io
-      :members:
-
-*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.
 
-
-.. todo:: Move this doc to another section
-
 Intersphinx
 -----------