mirror of
https://github.com/readthedocs/sphinx-autoapi
synced 2024-10-31 21:20:17 +00:00
129 lines
4.2 KiB
ReStructuredText
129 lines
4.2 KiB
ReStructuredText
Design Reference
|
|
================
|
|
|
|
Python
|
|
------
|
|
|
|
When choosing what to document,
|
|
AutoAPI aims to document anything 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,
|
|
that function is documented in both the submodule and the package.
|
|
There are some exceptions to this rule:
|
|
|
|
* Anything that is imported into a module is not documented.
|
|
Usually a module is where implementations exist.
|
|
Therefore an import of something is usually for the usage of the implementation,
|
|
and not as something to be accessed publicly.
|
|
* When the module or package defines an ``__all__``,
|
|
only the members named in ``__all__`` are documented.
|
|
* When a configuration option indicates that private
|
|
or special members should also be documented.
|
|
|
|
Furthermore, AutoAPI follows the same docstring inheritance rules as :func:`inspect.getdoc`,
|
|
with some exceptions:
|
|
|
|
* The docstrings of the following methods are not inherited because they are usually redundant:
|
|
|
|
* :meth:`object.__init__`
|
|
* :meth:`object.__new__`
|
|
* :meth:`type.__init__`
|
|
* :meth:`type.__new__`
|
|
|
|
|
|
Introduction
|
|
------------
|
|
|
|
We are working with Sphinx,
|
|
which has an existing way of doing this.
|
|
Generally, you define a `Domain` which describes the various language structure,
|
|
a *Class* or *Method*, for example.
|
|
Then the user will write RST that uses these definitions,
|
|
and Sphinx will create output from that markup.
|
|
|
|
.. code-block:: rst
|
|
|
|
.. py:function:: spam(eggs)
|
|
|
|
Spam the foo.
|
|
|
|
|
|
The author of the documentation will have now told Sphinx that the *spam* function exists in the Python project that is being documented.
|
|
|
|
Autogenerated Output
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Sphinx then built a series of tools to make the generation of this markup easier and more automatic:
|
|
|
|
* `Autodoc <http://sphinx-doc.org/ext/autodoc.html>`_
|
|
* `Autosummary <http://sphinx-doc.org/ext/autosummary.html>`_
|
|
|
|
Autodoc is a Python-only solution that imports the author's code into memory, and then allows the author to more automatically document full objects. For example, you can document a whole class on a page.
|
|
|
|
.. code-block:: py
|
|
|
|
.. autoclass:: Noodle
|
|
|
|
This will generate output that looks like:
|
|
|
|
.. class:: Noodle
|
|
:noindex:
|
|
|
|
Noodle's docstring.
|
|
|
|
There are also options for it to include a full listing of the classes attributes, methods, and other things, automatically.
|
|
|
|
.. warning:: Remember, this depends on ``Noodle`` being importable by the Python interpreter running Sphinx.
|
|
|
|
Proposed Architecture
|
|
---------------------
|
|
|
|
The proposed architecture for this project is as follows:
|
|
|
|
* A parser will read the source files into an internal representation of the objects that can be documented.
|
|
* Take the internal representation and generate in-memory rst that corresponds to the Sphinx domain objects.
|
|
* Sphinx will output HTML based on the doctree generated from the in-memory rst.
|
|
|
|
In diagram form::
|
|
|
|
Code -> Internal Objects -> RST -> Sphinx -> HTML
|
|
|
|
File Structure vs. Hierarchy
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Specific ID's should have one specific detail representation.
|
|
This means that every internal object should only have one place that it is rendered with a ``.. <domain>:<type>::`` canonical identifier.
|
|
All other places it is referenced should be in either:
|
|
|
|
* A reference
|
|
* A toctree (listing)
|
|
|
|
|
|
Sphinx Implementation
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The user will run a normal `make html` as part of the experience.
|
|
The generation and loading will be done as an extension that can be configured.
|
|
|
|
There will be Sphinx configuration for how things get built:
|
|
|
|
.. code-block:: rst
|
|
|
|
autoapi_root = 'api' # Where HTML is generated
|
|
autoapi_dirs = ['yaml'] # Directory of YAML sources
|
|
|
|
We will then loop over all source files in the ``autoapi_dir`` and parse them.
|
|
They will then be output into ``autoapi_root`` inside the documentation.
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
A nice example of Sphinx Python output similar to what we want:
|
|
|
|
* http://dta.googlecode.com/git/doc/_build/html/index.html
|
|
* Src: https://raw.githubusercontent.com/sfcta/dta/master/doc/index.rst
|
|
|
|
An example domain for Spec:
|
|
|
|
* https://subversion.xray.aps.anl.gov/bcdaext/specdomain/trunk/src/specdomain/sphinxcontrib/specdomain.py |