.. 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>`_.
Raw data
{
"_id": null,
"home_page": "",
"name": "sphinxcontrib-django",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Timo Brembeck <opensource@timo.brembeck.email>",
"keywords": "django,docstrings,extension,sphinx",
"author": "",
"author_email": "Diederik van der Boor <opensource@edoburu.nl>, Timo Brembeck <opensource@timo.brembeck.email>",
"download_url": "https://files.pythonhosted.org/packages/dc/28/92f6d685899fbd74a6c575c50dcc1abb8ab69c6da0160bc99d557d2104d1/sphinxcontrib-django-2.5.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/edoburu/sphinxcontrib-django/workflows/Tests/badge.svg\n :alt: GitHub Workflow Status\n :target: https://github.com/edoburu/sphinxcontrib-django/actions?query=workflow%3ATests\n.. image:: https://img.shields.io/pypi/v/sphinxcontrib-django.svg\n :alt: PyPi\n :target: https://pypi.org/project/sphinxcontrib-django/\n.. image:: https://codecov.io/gh/edoburu/sphinxcontrib-django/branch/main/graph/badge.svg\n :alt: Code coverage\n :target: https://codecov.io/gh/edoburu/sphinxcontrib-django\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :alt: Black Code Style\n :target: https://github.com/psf/black\n.. image:: https://img.shields.io/github/license/edoburu/sphinxcontrib-django\n :alt: GitHub license\n :target: https://github.com/edoburu/sphinxcontrib-django/blob/main/LICENSE\n.. image:: https://readthedocs.org/projects/sphinxcontrib-django/badge/?version=latest\n :alt: Documentation Status\n :target: https://sphinxcontrib-django.readthedocs.io/en/latest/?badge=latest\n\n|\n\n.. image:: https://raw.githubusercontent.com/edoburu/sphinxcontrib-django/main/docs/images/django-sphinx-logo-blue.png\n :width: 500\n :alt: logo\n :target: https://pypi.org/project/sphinxcontrib-django/\n\nsphinxcontrib-django\n=====================\n\nThis is a sphinx extension which improves the documentation of Django apps.\n\n\nFeatures\n--------\n\nImprovements for the output of Sphinx's autodoc for Django classes:\n\n* List all model and form fields as class parameters\n* Improve model field representations\n* Link related and reverse related fields to the referenced class\n* Hide irrelevant runtime information like ``declared_fieldsets``, ``fieldsets`` and ``Meta`` from\n classes\n* Add information about autogenerated methods\n* Fix intersphinx mappings to Django modules\n* Custom text roles to cross-reference the documentations of Django (``:setting:``,\n ``:templatetag:``, ``:templatefilter:``, ``:fieldlookup:``) and Sphinx (``:event:``,\n ``:confval:``)\n\n\nInstallation\n------------\n\nInstall the package via pip:\n\n.. code-block:: bash\n\n pip install sphinxcontrib-django\n\n\nConfiguration\n-------------\n\nAdd the following to your Sphinx config file ``conf.py``:\n\n.. code-block:: python\n\n # Add source directory to sys.path\n sys.path.insert(0, os.path.abspath(\"../src\"))\n\n # Add sphinxcontrib_django to installed extensions\n extensions = [\n \"sphinxcontrib_django\",\n ]\n\n # Configure the path to the Django settings module\n django_settings = \"myapp.settings\"\n\nOptionally, you can include the table names of your models in their docstrings with:\n\n.. code-block:: python\n\n # Include the database table names of Django models\n django_show_db_tables = True # Boolean, default: False\n # Add abstract database tables names (only takes effect if django_show_db_tables is True)\n django_show_db_tables_abstract = True # Boolean, default: False\n\nOptionally, you can extend amount of displayed choices in model fields with them:\n\n.. code-block:: python\n\n # Integer amount of model field choices to show, default 10\n django_choices_to_show = 10\n\nAdvanced Usage\n--------------\n\nIf you want to run custom code which depends on Django, e.g. to monkeypatch your application during documentation build,\nyou might run into an `ImproperlyConfigured <https://docs.djangoproject.com/en/stable/ref/exceptions/#improperlyconfigured>`_ exception:\n\n 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.\n\nTherefore, this Sphinx extension emits the event ``django-configured`` after ``django.setup()`` is finished, so you can\nrun your code the following way in ``conf.py``:\n\n.. code-block:: python\n\n def patch_django(app):\n \"\"\"\n Your custom code here\n \"\"\"\n\n def setup(app):\n app.connect(\"django-configured\", patch_django)\n\n\nContributing\n------------\n\nPull requests are always welcome!\n\nYou can install all requirements of the development setup with the extras ``dev``, ``test``, ``doc`` and ``optional``:\n\n.. code-block:: bash\n\n python3 -m venv .venv\n source .venv/bin/activate\n pip install -e .[dev,test,doc,optional]\n pre-commit install\n\nRun the tests and generate the coverage report with:\n\n.. code-block:: bash\n\n coverage run\n coverage html\n\nBuild the documentation with:\n\n.. code-block:: bash\n\n cd docs\n make html\n\nThe documentation is automatically deployed to `Read the Docs <https://sphinxcontrib-django.rtfd.io>`_.\n",
"bugtrack_url": null,
"license": "Apache2 2.0 License",
"summary": "Improve the Sphinx autodoc for Django classes.",
"version": "2.5",
"project_urls": {
"Bug Tracker": "https://github.com/edoburu/sphinxcontrib-django/issues",
"Documentation": "https://sphinxcontrib-django.readthedocs.io/",
"Release Notes": "https://github.com/edoburu/sphinxcontrib-django/blob/main/CHANGES.rst",
"Source Code": "https://github.com/edoburu/sphinxcontrib-django"
},
"split_keywords": [
"django",
"docstrings",
"extension",
"sphinx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "453c2de4b64abb71cf0f27f9e4401695d8843efed9fdd89ab49957f157a23519",
"md5": "a8731eb834e51ba88f661c05933c4dfe",
"sha256": "70148af4ccbb5184c5b1add939c3827c79a29a7d20ed18c25ceab347e3f14ca8"
},
"downloads": -1,
"filename": "sphinxcontrib_django-2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8731eb834e51ba88f661c05933c4dfe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21538,
"upload_time": "2023-09-26T17:54:34",
"upload_time_iso_8601": "2023-09-26T17:54:34.404021Z",
"url": "https://files.pythonhosted.org/packages/45/3c/2de4b64abb71cf0f27f9e4401695d8843efed9fdd89ab49957f157a23519/sphinxcontrib_django-2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dc2892f6d685899fbd74a6c575c50dcc1abb8ab69c6da0160bc99d557d2104d1",
"md5": "69e0ac4d72b2b1b22d4cce4257f2d928",
"sha256": "45a54c0cc1f641d6c15872828862f0738348ca8d7d5b92777bcaa530678c2cc4"
},
"downloads": -1,
"filename": "sphinxcontrib-django-2.5.tar.gz",
"has_sig": false,
"md5_digest": "69e0ac4d72b2b1b22d4cce4257f2d928",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23788,
"upload_time": "2023-09-26T17:54:36",
"upload_time_iso_8601": "2023-09-26T17:54:36.259664Z",
"url": "https://files.pythonhosted.org/packages/dc/28/92f6d685899fbd74a6c575c50dcc1abb8ab69c6da0160bc99d557d2104d1/sphinxcontrib-django-2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-26 17:54:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "edoburu",
"github_project": "sphinxcontrib-django",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinxcontrib-django"
}
JSON
