Made it clearer how to customise what objects AutoAPI will document.

Closes #339

docs/changes/339.doc.rst

@@ -0,0 +1 @@
+Made it clearer how to customise what objects AutoAPI will document.

docs/how_to.rst

@@ -8,6 +8,88 @@ set up already.
 If you don't know how to do this then read the :doc:`tutorials`.
 
 
+.. _customise-documented-api:
+
+How to Customise What Gets Documented
+-------------------------------------
+
+With the default settings,
+AutoAPI will document everything that is publicly accessible through the actual package
+when loaded in Python.
+For example if a function is imported from a submodule into a package
+then that function is documented in both the submodule and the package.
+
+However there are multiple options available for controlling what AutoAPI will document.
+
+
+Connect to the :event:`autoapi-skip-member` event
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :event:`autoapi-skip-member` event is emitted whenever
+a template has to decide whether a member should be included in the documentation.
+
+For example, to document only packages
+-- in other words, to not document submodules --
+you could implement an event handler in your conf.py like the following.
+
+.. code-block:: python
+
+    def skip_submodules(app, what, name, obj, skip, options):
+        if what == "module":
+            skip = True
+        return skip
+
+
+    def setup(sphinx):
+        sphinx.connect("autoapi-skip-member", skip_submodules)
+
+
+Set ``__all__``
+^^^^^^^^^^^^^^^
+
+AutoAPI treats the definition of `__all__ <https://docs.python.org/tutorial/modules.html#importing-from-a-package>`_
+as the specification of what objects are public in a module or package, and which aren't.
+
+In the following example, only ``func_a()`` and ``A`` would be documented.
+
+.. code-block:: python
+
+    # mypackage/__init__.py
+    from . import B
+
+    __all__ = ("A", "func_a")
+
+    class A:
+        ...
+
+    def func_a():
+        ...
+
+    def func_b():
+        ...
+
+
+Configure :confval:`autoapi_options`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :confval:`autoapi_options` configuration value gives some high level control
+over what is documented.
+For example you can hide members that don't have a docstring,
+document private members, and hide magic methods.
+See :confval:`autoapi_options` for more information on how to use this option.
+
+
+Customise the API Documentation Templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Finally, you can configure what gets rendered by customising the templates.
+This is a rather heavy handed approach,
+so it should only be necessary when the other options do not give you
+the control the you need.
+You can learn how to customise the templates in the next section;
+:ref:`customise-templates`.
+
+
 .. _customise-templates:
 
 How to Customise Layout Through Templates
@@ -38,6 +120,8 @@ For example, to override the Python class and module templates:
         └── module.rst
 
 
+.. _customise-index-page:
+
 How to Customise the Index Page
 -------------------------------
 

docs/reference/index.rst

@@ -4,7 +4,7 @@ Reference Guide
 
 The reference guide contains a detailed description of the
 configuration options, directives, and templates included in AutoAPI.
-To learn how to use AutoAPI, see the :doc:`tutorials`.
+To learn how to use AutoAPI, see the :doc:`/tutorials`.
 
 .. toctree::
 

docs/reference/templates.rst

@@ -57,7 +57,8 @@ that you can reliably access per language.
 .. warning::
 
 	These classes should not be constructed manually.
-	They can be reliably accessed through templates only.
+	They can be reliably accessed through templates
+	and :event:`autoapi-skip-member` only.
 
 Python
 ~~~~~~

docs/tutorials.rst

@@ -33,6 +33,22 @@ each language has a different set of steps for finishing the setup of AutoAPI.
 Python
 ^^^^^^
 
+..
+    Validate this section with the following commands:
+
+    $ mkdir mypackage
+    $ cd mypackage
+    $ mkdir mypackage
+    $ echo -e 'from ._client import Client\nfrom ._server import Server' > mypackage/__init__.py
+    $ echo -e 'class Client:\n    pass' > mypackage/_client.py
+    $ echo -e 'class Server:\n    pass' > mypackage/_server.py
+    $ touch README.md
+    $ python -m venv .venv
+    $ .venv/bin/pip install /path/to/sphinx-autoapi
+    $ .venv/bin/sphinx-quickstart --no-sep --project mypackage --author me -v 0.1.0 --release 0.1.0 --language en --extensions autoapi.extension docs
+    $ echo 'autoapi_dirs = ["../mypackage"]' >> docs/conf.py
+    $ .venv/bin/sphinx-build -b html docs/ docs/_build
+
 To enable the extension,
 we need to add it to the list of extensions in Sphinx's ``conf.py`` file::
 
@@ -104,6 +120,13 @@ AutoAPI will generate documentation when you run Sphinx!
     cd docs/
     sphinx-build -b html . _build
 
+With the documentation successfully built you should now be able to open
+the ``_build/index.html`` file in a web browser.
+The page will have a table of contents with a link to API reference
+documentation that has been generated by AutoAPI.
+
+Next, you might want to :ref:`customise what gets documented <customise-documented-api>`
+or :ref:`customise or remove the API reference index page <customise-index-page>`.
 
 Go
 ^^^

tox.ini

@@ -58,6 +58,7 @@ commands =
     sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
 
 [testenv:release_notes]
+skip_install = true
 deps =
     towncrier
 commands =