mirror of
https://github.com/readthedocs/sphinx-autoapi
synced 2024-11-10 01:10:27 +00:00
140 lines
4.2 KiB
ReStructuredText
140 lines
4.2 KiB
ReStructuredText
Sphinx AutoAPI
|
|
==============
|
|
|
|
.. image:: https://readthedocs.org/projects/sphinx-autoapi/badge/?version=latest
|
|
:target: https://sphinx-autoapi.readthedocs.org
|
|
:alt: Documentation
|
|
|
|
.. image:: https://travis-ci.org/readthedocs/sphinx-autoapi.svg?branch=master
|
|
:target: https://travis-ci.org/readthedocs/sphinx-autoapi
|
|
:alt: Travis Build Status
|
|
|
|
.. image:: https://ci.appveyor.com/api/projects/status/5nd33gp2eq7411t1?svg=true
|
|
:target: https://ci.appveyor.com/project/ericholscher/sphinx-autoapi
|
|
:alt: Appveyor Build Status
|
|
|
|
.. image:: https://img.shields.io/pypi/v/sphinx-autoapi.svg
|
|
:target: https://pypi.org/project/sphinx-autoapi/
|
|
:alt: PyPI Version
|
|
|
|
.. image:: https://img.shields.io/pypi/pyversions/sphinx-autoapi.svg
|
|
:target: https://pypi.org/project/sphinx-autoapi/
|
|
:alt: Supported Python Versions
|
|
|
|
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
|
|
:target: https://github.com/python/black
|
|
:alt: Formatted with Black
|
|
|
|
Sphinx AutoAPI provides "autodoc" style documentation for multiple programming languages
|
|
without needing to load, run, or import the project being documented.
|
|
|
|
In contrast to the traditional `Sphinx autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_,
|
|
which is Python-only and uses code imports,
|
|
AutoAPI finds and generates documentation by parsing source code.
|
|
|
|
Language Support
|
|
----------------
|
|
|
|
========== ====== ==========================================================
|
|
Language Status Parser
|
|
========== ====== ==========================================================
|
|
Python Stable Custom using `astroid <https://github.com/PyCQA/astroid>`_
|
|
Go Alpha `godocjson <https://github.com/readthedocs/godocjson>`_
|
|
Javascript Alpha `jsdoc <http://usejsdoc.org/>`_
|
|
.NET Alpha `docfx <https://dotnet.github.io/docfx/>`_
|
|
========== ====== ==========================================================
|
|
|
|
Getting Started
|
|
---------------
|
|
|
|
The following steps will walk through how to add AutoAPI to an existing Sphinx project.
|
|
For instructions on how to set up a Sphinx project,
|
|
see Sphinx's documentation on
|
|
`Getting Started <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_.
|
|
|
|
Installation
|
|
~~~~~~~~~~~~
|
|
|
|
AutoAPI can be installed through pip:
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install sphinx-autoapi
|
|
|
|
Next, add and configure AutoAPI in your Sphinx project's `conf.py`.
|
|
Other languages may require
|
|
`further configuration <https://sphinx-autoapi.readthedocs.io/en/latest/tutorials.html#setting-up-automatic-api-documentation-generation>`_:
|
|
|
|
.. code-block:: python
|
|
|
|
extensions.append('autoapi.extension')
|
|
|
|
autoapi_type = 'python'
|
|
autoapi_dirs = ['path/to/source/files', 'src']
|
|
|
|
Where `autoapi_type` can be one of any of the supported languages:
|
|
|
|
========== ================
|
|
Language ``autoapi_type``
|
|
========== ================
|
|
Python ``'python'``
|
|
Go ``'go'``
|
|
Javascript ``'javascript'``
|
|
.NET ``'dotnet'``
|
|
========== ================
|
|
|
|
When the documentation is built,
|
|
AutoAPI will now generate API documentation into an `autoapi/` directory and add an entry to the documentation in your top level table of contents!
|
|
|
|
To configure AutoAPI behaviour further,
|
|
see the `Configuration documentation <https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html>`_.
|
|
|
|
|
|
Contributing
|
|
------------
|
|
|
|
Running the tests
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
Tests are executed through `tox <https://tox.readthedocs.io/en/latest/>`_.
|
|
|
|
.. code-block:: bash
|
|
|
|
tox
|
|
|
|
Code Style
|
|
~~~~~~~~~~
|
|
|
|
Code is formatted using `black <https://github.com/python/black>`_.
|
|
|
|
You can check your formatting using black's check mode:
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e formatting
|
|
|
|
You can also get black to format your changes for you:
|
|
|
|
.. code-block:: bash
|
|
|
|
black autoapi/ tests/
|
|
|
|
You can even get black to format changes automatically when you commit using `pre-commit <https://pre-commit.com/>`_:
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install pre-commit
|
|
pre-commit install
|
|
|
|
Versioning
|
|
----------
|
|
|
|
We use `SemVer <http://semver.org/>`_ for versioning. For the versions available, see the `tags on this repository <https://github.com/readthedocs/sphinx-autoapi/tags>`_.
|
|
|
|
License
|
|
-------
|
|
|
|
This project is licensed under the MIT License.
|
|
See the `LICENSE.rst <LICENSE.rst>`_ file for details.
|