Skip to main content

Improve the Sphinx autodoc for Django classes.

Project description

GitHub Workflow Status PyPi Code coverage Black Code Style GitHub license Documentation Status

logo

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-django-2.5.tar.gz (23.8 kB view hashes)

Uploaded Source

Built Distribution

sphinxcontrib_django-2.5-py3-none-any.whl (21.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page