1. Writing documentation
Documentation changes generally come in two forms:
General improvements: typo corrections, error fixes and better explanations through clearer writing and more examples.
New features: documentation of features that have been added to the framework since the last release.
This section explains how you can craft your documentation changes in the most useful and least error-prone ways. 1
1.1. Getting started with Sphinx
The project’s documentation uses the Sphinx documentation system, which in turn is based on docutils. The basic idea is that lightly-formatted plain-text documentation is transformed into HTML, PDF, and any other output format.
To build the documentation locally, from the docs directory (this folder will hold the generated documentation and also all the assets you will need to generate your documentation) build the HTML:
$ make html
1.2. Configure Sphinx with Pearl Project
You have not yet configured Sphinx to fetch documentation from your project , to do this you will need to edit the /docs/conf.py file.
After the line import os add this
sys.path.insert(0, os.path.abspath('..'))
from django.conf import settings
settings.configure()
This configures Sphinx to look inside your project folder for docstrings. Inside your /docs folder add a modules folder to hold your documentation , for example add a views.rst file to hold your views documentation.
$ mkdir modules
$ touch modules/views.rst
Edit modules/views.rst and add the following
Views
======
.. automodule:: pearlproject.home.views
:members:
Sphinx (autodoc) will now look for through the views.py file in pearlcertification.home folder for doc-strings.
Finally you will need to include this documentation in your index.rst file, add this.
Contents:
.. toctree::
:maxdepth: 2
modules/views
Once you’ve done that go ahead and build the documentation
$ make html
Your documentation is now inside the build folder, take a look at your _build/html/index.html file. 2
For more details you can use the read the docs theme for generating docs.
You can use Markdown to make writing docs more simple
Markdown is a simple way to format text that looks great on any device. It doesn’t do anything fancy like change the font size, color, or type — just the essentials, using keyboard symbols you already know. For more information on markdown shortcuts Markdown Help