Metadata-Version: 2.4
Name: sphinxcontrib-django
Version: 2.5
Summary: Improve the Sphinx autodoc for Django classes.
Author-email: Diederik van der Boor <opensource@edoburu.nl>, Timo Brembeck <opensource@timo.brembeck.email>
Maintainer-email: Timo Brembeck <opensource@timo.brembeck.email>
License: Apache2 2.0 License
Project-URL: Bug Tracker, https://github.com/edoburu/sphinxcontrib-django/issues
Project-URL: Documentation, https://sphinxcontrib-django.readthedocs.io/
Project-URL: Release Notes, https://github.com/edoburu/sphinxcontrib-django/blob/main/CHANGES.rst
Project-URL: Source Code, https://github.com/edoburu/sphinxcontrib-django
Keywords: django,docstrings,extension,sphinx
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: Django>=3.2
Requires-Dist: Sphinx>=3.4.0
Requires-Dist: rich
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: doc
Requires-Dist: sphinx-last-updated-by-git; extra == "doc"
Requires-Dist: sphinx-rtd-theme; extra == "doc"
Provides-Extra: optional
Requires-Dist: django-mptt; extra == "optional"
Requires-Dist: django-phonenumber-field[phonenumbers]; extra == "optional"
Requires-Dist: psycopg2-binary; extra == "optional"
Provides-Extra: test
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-icdiff; extra == "test"
Requires-Dist: requests-mock; extra == "test"
Dynamic: license-file

sphinxcontrib-django
=====================

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

**🚨 See** `Configuration`_ **for Sphinx 9+ compatibility 🚨**

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"

.. _sphinx_9_compat:

**If you are using Sphinx >= 9 you must add the** `autodoc_use_legacy_class_based
<https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_use_legacy_class_based>`_
**setting:**

.. code-block:: python

    # Use legacy class-based autodoc implementation
    autodoc_use_legacy_class_based = True


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 <https://docs.djangoproject.com/en/stable/ref/exceptions/#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 <https://sphinxcontrib-django.rtfd.io>`_.
