{"id":20011747,"url":"https://github.com/sphinx-doc/sphinxcontrib-django","last_synced_at":"2025-04-07T13:09:13.777Z","repository":{"id":57469902,"uuid":"113442108","full_name":"sphinx-doc/sphinxcontrib-django","owner":"sphinx-doc","description":"This is a sphinx extension which improves the documentation of Django apps.","archived":false,"fork":false,"pushed_at":"2024-11-18T13:55:27.000Z","size":460,"stargazers_count":50,"open_issues_count":7,"forks_count":27,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-31T12:06:15.363Z","etag":null,"topics":["api-documentation","django","docstrings","python3","sphinx","sphinx-apidoc","sphinx-autodoc","sphinx-doc","sphinx-extension"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/sphinxcontrib-django/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sphinx-doc.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-07T11:23:33.000Z","updated_at":"2025-03-28T16:46:16.000Z","dependencies_parsed_at":"2024-01-06T18:02:49.300Z","dependency_job_id":"6df8e511-addc-4216-9234-4c14f2b42403","html_url":"https://github.com/sphinx-doc/sphinxcontrib-django","commit_stats":{"total_commits":159,"total_committers":15,"mean_commits":10.6,"dds":0.339622641509434,"last_synced_commit":"e9d43085ffc9b921fd7d880ff38d4e1d24d8d791"},"previous_names":["sphinx-doc/sphinxcontrib-django","edoburu/sphinxcontrib-django"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-doc%2Fsphinxcontrib-django","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-doc%2Fsphinxcontrib-django/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-doc%2Fsphinxcontrib-django/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-doc%2Fsphinxcontrib-django/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sphinx-doc","download_url":"https://codeload.github.com/sphinx-doc/sphinxcontrib-django/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247657281,"owners_count":20974345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-documentation","django","docstrings","python3","sphinx","sphinx-apidoc","sphinx-autodoc","sphinx-doc","sphinx-extension"],"created_at":"2024-11-13T07:27:21.201Z","updated_at":"2025-04-07T13:09:13.757Z","avatar_url":"https://github.com/sphinx-doc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. image:: https://github.com/sphinx-doc/sphinxcontrib-django/workflows/Tests/badge.svg\n    :alt: GitHub Workflow Status\n    :target: https://github.com/sphinx-doc/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/sphinx-doc/sphinxcontrib-django/branch/main/graph/badge.svg\n    :alt: Code coverage\n    :target: https://codecov.io/gh/sphinx-doc/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/sphinx-doc/sphinxcontrib-django\n    :alt: GitHub license\n    :target: https://github.com/sphinx-doc/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/sphinx-doc/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 \u003chttps://docs.djangoproject.com/en/stable/ref/exceptions/#improperlyconfigured\u003e`_ 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 \u003chttps://sphinxcontrib-django.rtfd.io\u003e`_.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphinx-doc%2Fsphinxcontrib-django","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsphinx-doc%2Fsphinxcontrib-django","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphinx-doc%2Fsphinxcontrib-django/lists"}