.. image:: https://github.com/timoludwig/sphinxcontrib-django2/workflows/Tests/badge.svg
    :alt: GitHub Workflow Status
    :target: https://github.com/timoludwig/sphinxcontrib-django2/actions?query=workflow%3ATests
.. image:: https://img.shields.io/pypi/v/sphinxcontrib-django2.svg
    :alt: PyPi
    :target: https://pypi.org/project/sphinxcontrib-django2/
.. image:: https://codecov.io/gh/timoludwig/sphinxcontrib-django2/branch/develop/graph/badge.svg
    :alt: Code coverage
    :target: https://codecov.io/gh/timoludwig/sphinxcontrib-django2
.. 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/timoludwig/sphinxcontrib-django2
    :alt: GitHub license
    :target: https://github.com/timoludwig/sphinxcontrib-django2/blob/develop/LICENSE
.. image:: https://readthedocs.org/projects/sphinxcontrib-django2/badge/?version=latest
    :alt: Documentation Status
    :target: https://sphinxcontrib-django2.readthedocs.io/en/latest/?badge=latest

|

.. image:: https://raw.githubusercontent.com/timoludwig/sphinxcontrib-django2/main/docs/images/django-sphinx-logo-blue.png
    :width: 500
    :alt: logo
    :target: https://pypi.org/project/sphinxcontrib-django2/

sphinxcontrib-django2
=====================

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:``)

This is a fork of `sphinxcontrib-django`_, which seems to be no longer maintained.

.. _sphinxcontrib-django: https://github.com/edoburu/sphinxcontrib-django


Installation
------------

Install the package via pip:

.. code-block:: bash

    pip install sphinxcontrib-django2


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_django2 to installed extensions
    extensions = [
        "sphinxcontrib_django2",
    ]

    # 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


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-django2.rtfd.io>`_.
