# 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:

    pip install sphinxcontrib-django

## Configuration

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

    # 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:

    # 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:

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

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

    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:

    coverage run
    coverage html

Build the documentation with:

    cd docs
    make html

The documentation is automatically deployed to Read the Docs.