.. image:: https://github.com/timoludwig/sphinxcontrib-django2/workflows/Tests/badge.svg
:alt: GitHub Workflow Status
:target: https://github.com/timoludwig/sphinxcontrib-django2/actions?query=workflow%3ATests
.. image:: https://img.shields.io/pypi/v/sphinxcontrib-django2.svg
:alt: PyPi
:target: https://pypi.org/project/sphinxcontrib-django2/
.. image:: https://codecov.io/gh/timoludwig/sphinxcontrib-django2/branch/develop/graph/badge.svg
:alt: Code coverage
:target: https://codecov.io/gh/timoludwig/sphinxcontrib-django2
.. 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/timoludwig/sphinxcontrib-django2
:alt: GitHub license
:target: https://github.com/timoludwig/sphinxcontrib-django2/blob/develop/LICENSE
.. image:: https://readthedocs.org/projects/sphinxcontrib-django2/badge/?version=latest
:alt: Documentation Status
:target: https://sphinxcontrib-django2.readthedocs.io/en/latest/?badge=latest
|
.. image:: https://raw.githubusercontent.com/timoludwig/sphinxcontrib-django2/main/docs/images/django-sphinx-logo-blue.png
:width: 500
:alt: logo
:target: https://pypi.org/project/sphinxcontrib-django2/
sphinxcontrib-django2
=====================
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:``)
This is a fork of `sphinxcontrib-django`_, which seems to be no longer maintained.
.. _sphinxcontrib-django: https://github.com/edoburu/sphinxcontrib-django
Installation
------------
Install the package via pip:
.. code-block:: bash
pip install sphinxcontrib-django2
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_django2 to installed extensions
extensions = [
"sphinxcontrib_django2",
]
# 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
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-django2.rtfd.io>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/timoludwig/sphinxcontrib-django2",
"name": "sphinxcontrib-django2",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Timo Ludwig",
"author_email": "ti.ludwig@web.de",
"download_url": "https://files.pythonhosted.org/packages/6a/fc/d9d5eba3d7d97d78ae9af063fb0635190c395e1716711a9831029457279c/sphinxcontrib-django2-1.6.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/timoludwig/sphinxcontrib-django2/workflows/Tests/badge.svg\n :alt: GitHub Workflow Status\n :target: https://github.com/timoludwig/sphinxcontrib-django2/actions?query=workflow%3ATests\n.. image:: https://img.shields.io/pypi/v/sphinxcontrib-django2.svg\n :alt: PyPi\n :target: https://pypi.org/project/sphinxcontrib-django2/\n.. image:: https://codecov.io/gh/timoludwig/sphinxcontrib-django2/branch/develop/graph/badge.svg\n :alt: Code coverage\n :target: https://codecov.io/gh/timoludwig/sphinxcontrib-django2\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/timoludwig/sphinxcontrib-django2\n :alt: GitHub license\n :target: https://github.com/timoludwig/sphinxcontrib-django2/blob/develop/LICENSE\n.. image:: https://readthedocs.org/projects/sphinxcontrib-django2/badge/?version=latest\n :alt: Documentation Status\n :target: https://sphinxcontrib-django2.readthedocs.io/en/latest/?badge=latest\n\n|\n\n.. image:: https://raw.githubusercontent.com/timoludwig/sphinxcontrib-django2/main/docs/images/django-sphinx-logo-blue.png\n :width: 500\n :alt: logo\n :target: https://pypi.org/project/sphinxcontrib-django2/\n\nsphinxcontrib-django2\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\nThis is a fork of `sphinxcontrib-django`_, which seems to be no longer maintained.\n\n.. _sphinxcontrib-django: https://github.com/edoburu/sphinxcontrib-django\n\n\nInstallation\n------------\n\nInstall the package via pip:\n\n.. code-block:: bash\n\n pip install sphinxcontrib-django2\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_django2 to installed extensions\n extensions = [\n \"sphinxcontrib_django2\",\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\n\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-django2.rtfd.io>`_.\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Improve the Sphinx autodoc for Django classes.",
"version": "1.6",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "404a9d5ae2ecc89ac8cb12c32b2d1c99",
"sha256": "44b62b249704bbf7b2617496d08117afce299eacf29e34fd9af6af6a31f065e5"
},
"downloads": -1,
"filename": "sphinxcontrib_django2-1.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "404a9d5ae2ecc89ac8cb12c32b2d1c99",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 20839,
"upload_time": "2022-11-24T02:14:24",
"upload_time_iso_8601": "2022-11-24T02:14:24.702221Z",
"url": "https://files.pythonhosted.org/packages/65/69/d9e02c72e25c5d7eaaf4abde98d9180ee829b88d11de24692667046fcb6f/sphinxcontrib_django2-1.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "e6471bb2ec754e4d257f457e27c478a6",
"sha256": "5df7660b528596994a47ac371afa9a44b78bbb26c43e30d53b1a835c909df044"
},
"downloads": -1,
"filename": "sphinxcontrib-django2-1.6.tar.gz",
"has_sig": false,
"md5_digest": "e6471bb2ec754e4d257f457e27c478a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19507,
"upload_time": "2022-11-24T02:14:26",
"upload_time_iso_8601": "2022-11-24T02:14:26.136872Z",
"url": "https://files.pythonhosted.org/packages/6a/fc/d9d5eba3d7d97d78ae9af063fb0635190c395e1716711a9831029457279c/sphinxcontrib-django2-1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-11-24 02:14:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "timoludwig",
"github_project": "sphinxcontrib-django2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinxcontrib-django2"
}
JSON
