Improve the Sphinx autodoc for Django classes.
Project description
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
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
Hashes for sphinxcontrib_django-2.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 70148af4ccbb5184c5b1add939c3827c79a29a7d20ed18c25ceab347e3f14ca8 |
|
MD5 | a8731eb834e51ba88f661c05933c4dfe |
|
BLAKE2b-256 | 453c2de4b64abb71cf0f27f9e4401695d8843efed9fdd89ab49957f157a23519 |