https://github.com/sphinx-doc/sphinxcontrib-django

This is a sphinx extension which improves the documentation of Django apps.
https://github.com/sphinx-doc/sphinxcontrib-django

api-documentation django docstrings python3 sphinx sphinx-apidoc sphinx-autodoc sphinx-doc sphinx-extension

Last synced: about 17 hours ago
JSON representation

This is a sphinx extension which improves the documentation of Django apps.

• Host: GitHub
• URL: https://github.com/sphinx-doc/sphinxcontrib-django
• Owner: sphinx-doc
• License: apache-2.0
• Created: 2017-12-07T11:23:33.000Z (about 7 years ago)
• Default Branch: main
• Last Pushed: 2024-11-18T13:55:27.000Z (2 months ago)
• Last Synced: 2025-01-15T22:18:47.951Z (8 days ago)
• Topics: api-documentation, django, docstrings, python3, sphinx, sphinx-apidoc, sphinx-autodoc, sphinx-doc, sphinx-extension
• Language: Python
• Homepage: https://pypi.org/project/sphinxcontrib-django/
• Size: 449 KB
• Stars: 46
• Watchers: 5
• Forks: 25
• Open Issues: 7
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGES.rst
  • License: LICENSE
  • Codeowners: .github/CODEOWNERS
  • Authors: AUTHORS

Awesome Lists containing this project

README

        
.. image:: https://github.com/sphinx-doc/sphinxcontrib-django/workflows/Tests/badge.svg

    :alt: GitHub Workflow Status

    :target: https://github.com/sphinx-doc/sphinxcontrib-django/actions?query=workflow%3ATests

.. image:: https://img.shields.io/pypi/v/sphinxcontrib-django.svg

    :alt: PyPi

    :target: https://pypi.org/project/sphinxcontrib-django/

.. image:: https://codecov.io/gh/sphinx-doc/sphinxcontrib-django/branch/main/graph/badge.svg

    :alt: Code coverage

    :target: https://codecov.io/gh/sphinx-doc/sphinxcontrib-django

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg

    :alt: Black Code Style

    :target: https://github.com/psf/black

.. image:: https://img.shields.io/github/license/sphinx-doc/sphinxcontrib-django

    :alt: GitHub license

    :target: https://github.com/sphinx-doc/sphinxcontrib-django/blob/main/LICENSE

.. image:: https://readthedocs.org/projects/sphinxcontrib-django/badge/?version=latest

    :alt: Documentation Status

    :target: https://sphinxcontrib-django.readthedocs.io/en/latest/?badge=latest

|

.. image:: https://raw.githubusercontent.com/sphinx-doc/sphinxcontrib-django/main/docs/images/django-sphinx-logo-blue.png

    :width: 500

    :alt: logo

    :target: https://pypi.org/project/sphinxcontrib-django/

sphinxcontrib-django

=====================

This is a sphinx extension which improves the documentation of Django apps.

Features

--------

Improvements for the output of Sphinx's autodoc for Django classes:

* List all model and form fields as class parameters

* Improve model field representations

* Link related and reverse related fields to the referenced class

* Hide irrelevant runtime information like ``declared_fieldsets``, ``fieldsets`` and ``Meta`` from

  classes

* Add information about autogenerated methods

* Fix intersphinx mappings to Django modules

* Custom text roles to cross-reference the documentations of Django (``:setting:``,

  ``:templatetag:``, ``:templatefilter:``, ``:fieldlookup:``) and Sphinx (``:event:``,

  ``:confval:``)

Installation

------------

Install the package via pip:

.. code-block:: bash

    pip install sphinxcontrib-django

Configuration

-------------

Add the following to your Sphinx config file ``conf.py``:

.. code-block:: python

    # Add source directory to sys.path

    sys.path.insert(0, os.path.abspath("../src"))

    # Add sphinxcontrib_django to installed extensions

    extensions = [

        "sphinxcontrib_django",

    ]

    # Configure the path to the Django settings module

    django_settings = "myapp.settings"

Optionally, you can include the table names of your models in their docstrings with:

.. code-block:: python

    # Include the database table names of Django models

    django_show_db_tables = True                # Boolean, default: False

    # Add abstract database tables names (only takes effect if django_show_db_tables is True)

    django_show_db_tables_abstract = True       # Boolean, default: False

Optionally, you can extend amount of displayed choices in model fields with them:

.. code-block:: python

    # Integer amount of model field choices to show, default 10

    django_choices_to_show = 10

Advanced Usage

--------------

If you want to run custom code which depends on Django, e.g. to monkeypatch your application during documentation build,

you might run into an `ImproperlyConfigured `_ exception:

    Requested setting INSTALLED_APPS, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

Therefore, this Sphinx extension emits the event ``django-configured`` after ``django.setup()`` is finished, so you can

run your code the following way in ``conf.py``:

.. code-block:: python

    def patch_django(app):

        """

        Your custom code here

        """

    def setup(app):

        app.connect("django-configured", patch_django)

Contributing

------------

Pull requests are always welcome!

You can install all requirements of the development setup with the extras ``dev``, ``test``, ``doc`` and ``optional``:

.. code-block:: bash

    python3 -m venv .venv

    source .venv/bin/activate

    pip install -e .[dev,test,doc,optional]

    pre-commit install

Run the tests and generate the coverage report with:

.. code-block:: bash

    coverage run

    coverage html

Build the documentation with:

.. code-block:: bash

    cd docs

    make html

The documentation is automatically deployed to `Read the Docs `_.