django-docs

django-docs

.. image:: https://img.shields.io/travis/littlepea/django-docs.svg?style=flat-square :target: http://travis-ci.org/littlepea/django-docs

.. image:: https://img.shields.io/pypi/v/django-docs.svg?style=flat-square :target: https://pypi.python.org/pypi/django-docs/

.. image:: https://img.shields.io/badge/license-New%20BSD-blue.svg?style=flat-square :target: https://raw.githubusercontent.com/littlepea/django-docs/master/LICENSE

django-docs allows to serve Sphinx generated docs directly from Django.

Dependencies

• Python 3.6+ for Django 3.0 or higher

Credits

• Project on GitHub: littlepea/django-docs <https://github.com/littlepea/django-docs/>_
• Documentation on Read The Docs <https://django-docs.readthedocs.org/>_
• Maintained by Evgeny Demchenko <https://github.com/littlepea>_

Installation

1. Install django-docs package::

   pip install django-docs

2. Add docs to INSTALLED_APPS in settings.py::

   INSTALLED_APPS = ( ... 'docs', ... )

3. Add docs.urls to urls.py::

   urlpatterns = [ ... url(r'^docs/', include('docs.urls')), ... ]

4. Customize configuration::

   DOCS_ROOT = os.path.join(PROJECT_PATH, '../docs/_build/html') DOCS_ACCESS = 'staff'

Configuration

DOCS_ROOT (required) ^^^^^^^^^^^^^^^^^^^^

Absolute path to the root directory of html docs generated by Sphinx (just like STATIC_ROOT / MEDIA_ROOT settings).

DOCS_ACCESS (optional) ^^^^^^^^^^^^^^^^^^^^^^

Docs access level (public by default). Possible values:

• public - (default) docs are visible to everyone
• login_required - docs are visible only to authenticated users
• staff - docs are visible only to staff users (user.is_staff == True)
• superuser - docs are visible only to superusers (user.is_superuser == True)

Running the tests

Make sure to install test_requirements.txt first::

pip install -r test_requirements.txt
pip install -e .

You can run the tests with via::

python setup.py test

or::

python docs/tests/runtests.py

To run all tests against different versions of Django simply run::

tox

Running the example project

Make sure to install requirements.txt first::

virtualenv env
. env/bin/activate
pip install -r test_requirements.txt
pip install -e .

You can run the example project with via::

cd example
python manage.py migrate
python manage.py runserver

Screenshot

.. image:: https://www.evernote.com/l/AHRVMNRZKLVPaoCgJouF_-Pz7rfeDzGF32sB/image.png