.. 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/
This is a sphinx extension which improves the documentation of Django apps.
Improvements for the output of Sphinx's autodoc for Django classes:
declared_fieldsets
, fieldsets
and Meta
from
classes:setting:
,
:templatetag:
, :templatefilter:
, :fieldlookup:
) and Sphinx (:event:
,
:confval:
)Install the package via pip:
.. code-block:: bash
pip install sphinxcontrib-django
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
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)
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>
_.