https://github.com/readthedocs/sphinx-autoapi
A new approach to API documentation in Sphinx.
https://github.com/readthedocs/sphinx-autoapi
Last synced: 7 months ago
JSON representation
A new approach to API documentation in Sphinx.
- Host: GitHub
- URL: https://github.com/readthedocs/sphinx-autoapi
- Owner: readthedocs
- License: mit
- Created: 2015-05-29T19:32:28.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2025-02-18T01:50:12.000Z (10 months ago)
- Last Synced: 2025-05-08T05:51:36.642Z (7 months ago)
- Language: Python
- Homepage: https://sphinx-autoapi.readthedocs.io/
- Size: 4.19 MB
- Stars: 461
- Watchers: 14
- Forks: 137
- Open Issues: 62
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- License: LICENSE.rst
Awesome Lists containing this project
README
Sphinx AutoAPI
==============
.. image:: https://readthedocs.org/projects/sphinx-autoapi/badge/?version=latest
:target: https://sphinx-autoapi.readthedocs.org
:alt: Documentation
.. image:: https://github.com/readthedocs/sphinx-autoapi/actions/workflows/main.yml/badge.svg?branch=main
:target: https://github.com/readthedocs/sphinx-autoapi/actions/workflows/main.yml?query=branch%3Amain
:alt: Github 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-ruff-000000.svg
:target: https://docs.astral.sh/ruff/
:alt: Formatted with Ruff
Sphinx AutoAPI is a Sphinx extension for generating complete API documentation
without needing to load, run, or import the project being documented.
In contrast to the traditional `Sphinx autodoc `_,
which requires manual authoring and uses code imports,
AutoAPI finds and generates documentation by parsing source code.
For more information, see `the full documentation `_.
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 `_.
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`.
.. code-block:: python
extensions.append('autoapi.extension')
autoapi_dirs = ['path/to/source/files', 'src']
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 `_.
Contributing
------------
Running the tests
~~~~~~~~~~~~~~~~~
Tests are executed through `tox `_.
.. code-block:: bash
tox
Code Style
~~~~~~~~~~
Code is formatted using `ruff `_.
You can check your formatting using ruff format's check mode:
.. code-block:: bash
tox -e format
You can also get ruff to format your changes for you:
.. code-block:: bash
ruff format
Release Notes
~~~~~~~~~~~~~
Release notes are managed through `towncrier `_.
When making a pull request you will need to create a news fragment to document your change:
.. code-block:: bash
tox -e release_notes -- create --help
Versioning
----------
We use `SemVer `_ for versioning. For the versions available, see the `tags on this repository `_.
License
-------
This project is licensed under the MIT License.
See the `LICENSE.rst `_ file for details.