Improve the Sphinx autodoc for Django classes.
Project description
sphinxcontrib-django
Improvements for the output of Sphinx’s autodoc for Django classes.
This adds the following improvements:
Properly show which fields a model has.
Properly show which fields a form has.
Document the model fields as parameters in the model __init__().
Link foreign key and related fields to the documentation of the referenced class.
Hide irrelevant runtime information like declared_fieldsets, fieldsets and Meta from classes.
A :django:setting: role to allow linking to Django documentation. (e.g. :django:setting:`SITE_ID`)
Installation
Usage:
pip install sphinxcontrib-djangoAdd to the Sphinx config file (conf.py):
extensions = [
'sphinx.ext.autodoc',
'sphinxcontrib_django',
]Autodoc works by importing your code on the fly, and extracting the data from the Python classes. Thus, the project should be able to import Django models. Typically the following needs to be added to conf.py:
sys.path.insert(0, os.path.abspath('../src'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'myapp.settings'
django.setup()To support the :django:setting: role, configure Intersphinx:
intersphinx_mapping = {
'http://docs.python.org/': None,
'https://docs.djangoproject.com/en/stable': 'https://docs.djangoproject.com/en/stable/_objects',
}Recommendations:
When your project uses Celery, include celery.contrib.sphinx too. This adds an autotask:: directive, and :task:`app.tasks.my_task` role.
Other great extensions are:
sphinx-autodoc-annotation: Converts Python 3 annotations to docstrings.
sphinx.ext.graphviz: Allows to create diagrams with ease.
An example configuration may look like:
extensions = [
'sphinx.ext.autodoc', # The autodoc core
'sphinx.ext.graphviz', # Support creating charts!
'celery.contrib.sphinx', # Celery improvements!
'sphinx_autodoc_annotation', # Parses Python 3 annotations
'sphinxcontrib_django', # this module
]Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file sphinxcontrib-django-0.5.tar.gz.
File metadata
- Download URL: sphinxcontrib-django-0.5.tar.gz
- Upload date:
- Size: 13.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.20.0 setuptools/38.5.2 requests-toolbelt/0.8.0 tqdm/4.19.6 CPython/3.6.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 95831d5d58f780010b0255f298ea03d6bbf971c0f94f631268abd4320400b7db |
|
| MD5 | e7eb6a10c2be81863da48f1a91a592f6 |
|
| BLAKE2b-256 | 4b5c2efa5ee6fb1d5ee968fec9b07a1be69af2b70a684c909ad25b18ff1a334b |
File details
Details for the file sphinxcontrib_django-0.5-py2.py3-none-any.whl.
File metadata
- Download URL: sphinxcontrib_django-0.5-py2.py3-none-any.whl
- Upload date:
- Size: 14.2 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.20.0 setuptools/38.5.2 requests-toolbelt/0.8.0 tqdm/4.19.6 CPython/3.6.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | f5bb52d20b64b51087b44247789adaebfc51fa2fad71bfed42c4ca6c05723838 |
|
| MD5 | c70f6d8f3f9eae431c91269268cef3b5 |
|
| BLAKE2b-256 | 2a4a18ed8a53508fb24982afa9fd2fbcf7b60724497eea79407925afcd820e18 |
