Sphinx, the Python documentation generator, is an invaluable tool for developers and software projects. It offers a straightforward and efficient way to create professional-looking documentation for Python codebases.
With Sphinx, developers can effortlessly generate comprehensive documentation in various formats, including HTML, PDF, and other formats from “reStructuredText” source files. The tools rich feature set includes automatic API documentation, cross-referencing, code highlighting, and customizable themes. By using Sphinx, developers can enhance the accessibility, maintainability, and overall quality of their Python projects, fostering better understanding and adoption among users and contributors alike.
By integrating Sphinx into your Django app, you can leverage the existing infrastructure and framework of your application. This means that your documentation becomes an integral part of your project, seamlessly integrated with your existing codebase. It simplifies deployment and maintenance processes, as you don't need to manage multiple servers or separate deployments for your documentation.
This level of integration allows you to leverage the authentication and authorization mechanisms provided by Django. You can control access to the documentation based on user roles and permissions, ensuring that only authorized users can view sensitive or internal documentation.
While Sphinx's integration with Django provides features like seamless deployment, authentication control, code-documentation linking, and customization options, our focus will be on setting up Sphinx, selecting a custom theme, and utilizing Django’s authentication system to control documentation access.
Environment Overview
To follow along with this blog, you can either clone the repository or make sure you meet the following requirements:
Python
Install Python on your system. You can download the latest version from Python's official website.
Virtual Environment
Create a python virtual environment using the command:
python -m venv venv (On Windows)
python3 -m venv venv (On Unix or MacOS)Activate an existing virtual environment using the command:
.\venv\Scripts\activate (On Windows)
source venv/bin/activate (On Unix or MacOS)Integrated Development Environment (IDE)
While not mandatory, using an IDE like Visual Studio Code or PyCharm can enhance your development experience.
Pre-existing Django Application
Have an existing Django web application ready, as this guide focuses on integrating Sphinx into an established Django project.
Sphinx Theming
The guide uses the “sphinx-rtd-theme” for documentation styling. If you prefer other themes, explore options at Sphinx Themes.
Disclaimer: It is strongly advised to NOT test this in your production environment.
Installing Dependencies
This blog focuses specifically on the integration of Sphinx into an existing Django application and does not cover the Django setup process. The demonstration will utilize a basic Django web application to illustrate the integration of Sphinx. You can find all the code used in this demonstration linked below.
For this blog we will need to install the following python modules, additionally they will be linked below:
pip install sphinx
pip install django-docs
pip install sphinx-rtd-themeWhile we already know plenty about Sphinx, Django-Docs is the module we will be leveraging to seamlessly integrate Sphinx into our Django project.
Additionally, we'll illustrate the process of applying a custom theme to Sphinx, using the 'Read The Docs' theme for demonstration.
Configure Sphinx in Django
Now that we have our dependencies installed, it’s time to configure settings in django. First, we need to add the ‘docs’ app to our Django INSTALLED_APPS in settings.py:
INSTALLED_APPS = [
. . .
'docs',
]Next, we need configure our docs endpoint in urls.py:
urlpatterns = [
. . .
path('docs/', include('docs.urls')),
]Finally, we define the DOCS_ROOT variable in settings.py:
DOCS_ROOT = os.path.join(BASE_DIR, 'docs/_build/html')As an optional setting we can utilize Django’s built-in authentication package to provide access control to our newly created docs endpoint by adding the setting DOCS_ACCESS in settings.py:
DOCS_ACCESS = 'public'By default, access is set to public, but again if your project’s authentication is built from ‘django.contrib.auth’ then you can set this value to any of the following to fit the use case:
Sphinx Setup
To configure Sphinx in our Django project we will begin by creating a docs folder in our root directory:
Initially our docs folder is empty, when we enter the directory and use sphinx’s quickstart command it will automatically generate all the files needed to create and compile our own documentation.
cd docs
sphinx-quickstartA few prompts will appear when setting up Sphinx for the first time:
When setting up Sphinx, you'll be prompted to decide whether to separate the source and build directories—a user preference. Sphinx will also ask for details such as 'Project Name,' 'Author Name(s),' and 'Project Release,' allowing you the flexibility to be whatever you choose.
Once finished our docs folder should look like this:
Now we can configure our theme in docs/source/conf.py.
extensions = [
'sphinx_rtd_theme',
]Also:
html_theme = 'sphinx_rtd_theme'With that we can compile our source rst files:
./make htmlNow with our Django server running we can navigate over to http://127.0.0.1:8000/docs to see our documentation.
Conclusion
In summary, Sphinx is a vital tool for Python developers, streamlining the creation of professional documentation. Integrating Sphinx with Django simplifies deployment and maintenance, aligning documentation with the framework's infrastructure and enabling control over access using Django's authentication system. This powerful combination enhances project accessibility, maintainability, and security, with a focus on easy setup, theme selection, and leveraging Django's authentication for restricted documentation access. At 5.15 Technologies, we're more than just a development partner; we're your gateway to excellence. Our expertise goes beyond code and design, rooted in a deep understanding of industry best practices. We're dedicated to ensuring your web projects not only meet but exceed expectations. With a commitment to innovation, streamlined development, and a passion for excellence, we're here to guide you through new projects, revamps, or optimization.
Reach out to 5.15, and together, we'll set new benchmarks in excellence.