DOC: Add autodoc section "Ensuring the code can be imported"

This explains the requirements for importablilty (can be found and
dependencies can be resolved). It also explains two common approaches
how this can be achieved.

doc/usage/extensions/autodoc.rst

@@ -12,13 +12,6 @@
 This extension can import the modules you are documenting, and pull in
 documentation from docstrings in a semi-automatic way.
 
-.. note::
-
-   For Sphinx (actually, the Python interpreter that executes Sphinx) to find
-   your module, it must be importable.  That means that the module or the
-   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
@@ -44,6 +37,38 @@ docstrings to correct reStructuredText before :mod:`autodoc` processes them.
 .. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
 
 
+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 modules
+can be found by sphinx and that dependencies can be resolved (if your module does
+``import foo``, but ``foo`` is not available in the python environment that Sphinx
+runs in, your module import will fail).
+
+There are two ways to ensure this:
+
+1. Use an environment that contains your package and Sphinx. This can e.g. be your
+   local dev environment (with an editable install), or an environment in CI in which
+   you install Sphinx and your package. The regular installation process ensures that
+   your package can be found by sphinx and that all dependencies are available.
+
+2. It is alternatively possible to patch the Sphinx run so that it can operate directly
+   on the sources; e.g. if you want to be able to do a sphinx build from a source
+   checkout.
+
+   - Patch ``sys.path`` in your Sphinx :file:`conf.py` to include the folder of your
+     sources. E.g. if you have a repository structure with :file:`doc/conf.py` and
+     your package is at :file:`src/mypackage`, then you sould add::
+
+        sys.path.insert(0, os.path.abspath('../src'))
+
+     to your :file:`conf.py`.
+
+   - To cope with missing dependencies, specify the missing modules in
+     :confval:`autodoc_mock_imports`.
+
+
 Directives
 ----------