From aab9f814b8fd5033f2a73b67dbddae7989d06711 Mon Sep 17 00:00:00 2001 From: Ashley Whetter Date: Mon, 22 May 2023 09:38:24 -0700 Subject: [PATCH] Made it clearer how to customise what objects AutoAPI will document. Closes #339 --- docs/changes/339.doc.rst | 1 + docs/how_to.rst | 84 ++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 2 +- docs/reference/templates.rst | 3 +- docs/tutorials.rst | 23 ++++++++++ tox.ini | 1 + 6 files changed, 112 insertions(+), 2 deletions(-) create mode 100644 docs/changes/339.doc.rst diff --git a/docs/changes/339.doc.rst b/docs/changes/339.doc.rst new file mode 100644 index 00000000..9917a8d2 --- /dev/null +++ b/docs/changes/339.doc.rst @@ -0,0 +1 @@ +Made it clearer how to customise what objects AutoAPI will document. diff --git a/docs/how_to.rst b/docs/how_to.rst index 94f41013..5bf211bb 100644 --- a/docs/how_to.rst +++ b/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__ `_ +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 ------------------------------- diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 60f24144..eabdb1bb 100644 --- a/docs/reference/index.rst +++ b/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:: diff --git a/docs/reference/templates.rst b/docs/reference/templates.rst index 81884f1b..45583c50 100644 --- a/docs/reference/templates.rst +++ b/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 ~~~~~~ diff --git a/docs/tutorials.rst b/docs/tutorials.rst index 5e206377..0e98a9aa 100644 --- a/docs/tutorials.rst +++ b/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 ` +or :ref:`customise or remove the API reference index page `. Go ^^^ diff --git a/tox.ini b/tox.ini index f7d1aa71..3b1a2ac9 100644 --- a/tox.ini +++ b/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 =