1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
.. image:: https://github.com/edoburu/sphinxcontrib-django/workflows/Tests/badge.svg
:alt: GitHub Workflow Status
:target: https://github.com/edoburu/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/edoburu/sphinxcontrib-django/branch/main/graph/badge.svg
:alt: Code coverage
:target: https://codecov.io/gh/edoburu/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/edoburu/sphinxcontrib-django
:alt: GitHub license
:target: https://github.com/edoburu/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/edoburu/sphinxcontrib-django/main/docs/images/django-sphinx-logo-blue.png
:width: 500
:alt: logo
:target: https://pypi.org/project/sphinxcontrib-django/
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:
.. 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"
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>`_.
|
