Skip to content

Marina Mele's site

Reflections on family, values, and personal growth

Menu
  • Home
  • About
Menu

Document your Django projects: reStructuredText and Sphinx

Posted on March 30, 2014September 26, 2014 by Marina Mele

Check this post to learn how to document a Django project!
You’ll get an introduction to the reStructuredText markup language, learn how to install Sphinx, a library that takes the docstrings of your code and compiles them into nice html pages, and configure it for a Django project.

Documenting your project is very important, you know that — that’s why you’re reading this don’t you?
😉

For me, the most important reasons why you should document_your_projectsdocument your projects are:

  • It will help you understand what you did — specially a few months after you wrote the code.
  • It will help others understand what you did — this way, they can help you improve your code or add some extensions and functionalities.

Here, you’ll learn how to install and use Sphinx, a library that takes the docstrings of your code and compiles them into nice html pages. It’s used to create the official documentation of Python, Django, and most of all other popular Python packages.

But how? How does it compile them into nice pages with headers, links and other common formats? Well, you have to write your docstrings using reStructuredText (frequently abbreviated as reST), a markup format. But don’t worry, that’s easy to learn! 😉

Install Sphinx

Activate your virtual environment and install Sphinx, which is in the Python package Index and can be installed via pip or via easy_install:

$ pip install sphinx

This command will also install the following packages: Pygments, docutils, Jinja2 and markupsafe. Don’t forget to add them into you requirements.txt file. If you have different requirements files for production, developing and testing, I recommend you include Sphinx on the last two (not in production).

Create the docs folder

Now, we will create the docs folder using Sphinx:

$ sphinx-quickstart

Which will ask you different questions. I will show my answers using different colors: blue and red. Make sure you answer the same as me when they are red 😉

Enter the root path for documentation.
> Root path for the documentation [.]: ./docs

You have two options for placing the build directory for Sphinx output.
Either, you use a directory “_build” within the root path, or you separate
“source” and “build” directories within the root path.
> Separate source and build directories (y/n) [n]: n

Inside the root directory, two more directories will be created; “_templates”
for custom HTML templates and “_static” for custom stylesheets and other static
files. You can enter another prefix (such as “.”) to replace the underscore.
> Name prefix for templates and static dir [_]: _

The project name will occur in several places in the built documentation.
> Project name: myproject
> Author name(s): Marina Mele

Sphinx has the notion of a “version” and a “release” for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don’t need this dual structure,
just set both to the same value.
> Project version: 1.0
> Project release [1.0]: 1.0

The file name suffix for source files. Commonly, this is either “.txt”
or “.rst”.  Only files with this suffix are considered documents.
> Source file suffix [.rst]: .rst

One document is special in that it is considered the top node of the
“contents tree”, that is, it is the root of the hierarchical structure
of the documents. Normally, this is “index”, but if your “index”
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: index

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]: n

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n
> todo: write “todo” entries that can be shown or hidden on build (y/n) [n]: n
> coverage: checks for documentation coverage (y/n) [n]: y
> pngmath: include math, rendered as PNG images (y/n) [n]: n
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: n
> viewcode: include links to the source code of documented Python objects (y/n) [n]: n

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. ‘make html’ instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: n

This will create a docs folder inside your project folder, containing the files conf.py, index.rst and Makefile, and the folders _build, _static and _templates (which will be empty).

The autodoc extension is needed to import the docstrings of your project files into the documentation.

Create the html files

Inside the docs folder, type:

$ make html

This will create the html pages, which you’ll find in the _build/html folder. Open the index.html file and take a look at what has been created.

You’ll see that the document is essentially empty, as you must indicate sphinx where your project is. So… let’s tell him!

Open the conf.py file (inside the docs folder), and after the lines:

import sys
import os

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath(‘.’))

add the following:

sys.path.insert(0, os.path.abspath(‘..’))
from django.conf import settings
settings.configure()

This will tell sphinx where it should look for your project files.

Now, inside the docs folder create a modules folder with a models.rst file inside:

$ mkdir modules
$ touch modules/models.rst

Edit this file and write the following:

Models
======
.. automodule:: myproject.myapp.models
    :members:

Where myproject.myapp.models is the path form the folder that contains the docs folder and your app/models.py. This indicates autodoc that it should read the models.py file looking for docstrings.

However, we still need to include the models.rst file. To do this, open the file docs/index.rst and write:

Contents:
.. toctree::
   :maxdepth: 2

   modules/models

Now, let’s try again with

$ make html

and look at your _build/html/index.html file. You should see a link to Models, containing all the models you have defined there, together with its methods! 😉

Now, you can add as many files you want to document all your project! Moreover, you should learn a little bit more about reStructuredText to make your docs nicer 😉

Don’t forget to share and +1 if useful, thanks! 😉

Marina Melé
Marina Mele

Marina Mele has experience in artificial intelligence implementation and has led tech teams for over a decade. On her personal blog (marinamele.com), she writes about personal growth, family values, AI, and other topics she’s passionate about. Marina also publishes a weekly AI newsletter featuring the latest advancements and innovations in the field (marinamele.substack.com)

Leave a Reply Cancel reply

You must be logged in to post a comment.

Categories

  • Personal Growth and Development
  • Artificial Intelligence
  • Mindful Parenting and Family Life
  • Productivity and Time Management
  • Mindfulness and Wellness
  • Values and Life Lessons
  • Posts en català
  • Other things to learn

Recent Posts

  • BlueSky Social – A Sneak Peek at the Future of Social Media
  • The Incredible Journey of AI Image Generation
  • AI and Fundamental Rights: How the AI Act Aims to Protect Individuals
  • Overcoming Regrets: Finding the Strength to Move Forward
  • Thinking Outside the Box: Creative Problem-Solving with Critical Thinking

RSS

  • Entries RSS
Follow @marina_mele
  • Cookie Policy
  • Privacy Policy
©2023 Marina Mele's site | Built using WordPress and Responsive Blogily theme by Superb
This website uses cookies to improve your experience. If you keep navigating through this website, we'll assume you're ok with this, but you can opt-out if you wish.Accept Read More
Privacy & Cookies Policy

Privacy Overview

This website uses cookies to improve your experience while you navigate through the website. Out of these, the cookies that are categorized as necessary are stored on your browser as they are essential for the working of basic functionalities of the website. We also use third-party cookies that help us analyze and understand how you use this website. These cookies will be stored in your browser only with your consent. You also have the option to opt-out of these cookies. But opting out of some of these cookies may affect your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This category only includes cookies that ensures basic functionalities and security features of the website. These cookies do not store any personal information.
Non-necessary
Any cookies that may not be particularly necessary for the website to function and is used specifically to collect user personal data via analytics, ads, other embedded contents are termed as non-necessary cookies. It is mandatory to procure user consent prior to running these cookies on your website.
SAVE & ACCEPT