https://github.com/readthedocs/sphinx-autoapi

A new approach to API documentation in Sphinx.
https://github.com/readthedocs/sphinx-autoapi

Last synced: 3 days 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 9 years ago)
• Default Branch: main
• Last Pushed: 2024-11-30T01:08:43.000Z (about 2 months ago)
• Last Synced: 2025-01-11T19:32:21.408Z (9 days ago)
• Language: Python
• Homepage: https://sphinx-autoapi.readthedocs.io/
• Size: 4.21 MB
• Stars: 446
• Watchers: 14
• Forks: 135
• Open Issues: 63
• 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.