2

Python Documentation using Sphinx

 3 years ago
source link: https://www.patricksoftwareblog.com/python-documentation-using-sphinx/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.

Introduction:

I’ve seen multiple instances at work, in source code examples, and even from open source projects where the documentation of the code was non-existent or insufficient. A lot of times as software developers, it is easy to disregard documenting your code as you’re just trying to get your program to work. Haven’t you heard or thought this before: “I can get the documentation together once I get everything running smoothly.” Never happens!

Overview:

Just like setting up a good infrastructure for writing your unit tests, setting up a good infrastructure for your documentation is important to starting off a python project correctly. In this blog post, I’ll provide examples of how I like to set up the documentation for my python project using Sphinx. By properly documenting your source code, Sphinx will be able to generate nice looking documentation (I like HTML) for your project.

Getting Started:

First, you will need to install Sphinx:

pip install sphinx

Next, create a ‘docs’ folder in your project, so that you overall project structure looks similar to:

project_name
project_name
__init__.py
source_file_1.py
source_file_2.py
docs
run.py

Within the ‘docs’ folder that you just created, run the ‘sphinx-quickstart’ script to perform the necessary setup. You can use the default settings for every choice, but I would recommend changing the following selections:

> Separate source and build directories (y/n) [n]: y
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> Create Windows command file? (y/n) [y]: n

Here’s the command:

(py_doc) $ pwd
.../python_test_projects/python_documentation/docs
(py_doc) $ sphinx-quickstart

This script created a number of directories and files within the ‘docs’ folder, which will be used to auto-generate documentation from your source code.

Adding Comments to Source Code:

It’s very easy to start writing a file/class with just the code that you need, but this does not lead to maintainable code. Here’s a source code file without any comments:

class BasicClass(object):
def __init__(self):
self.current_number = 0
def increment_number(self):
self.current_number += 1
def decrement_number(self):
self.current_number -= 1
def clear_number(self):
self.current_number = 0

After doing some research on how to document python source code, I updated this file to:

"""
.. module:: project_documentation
:platform: OS X
:synopsis: module illustrating how to document python source code
.. moduleauthor:: Patrick Kennedy <[email protected]>
"""
class BasicClass(object):
"""Class illustrating how to document python source code
This class provides some basic methods for incrementing, decrementing,
and clearing a number.
.. note::
This class does not provide any significant functionality that the
python does not already include. It is just for illustrative purposes.
"""
def __init__(self):
"""A simple initialization method.
Args:
None
"""
self.current_number = 0
def increment_number(self):
"""Method to increment the number.
Args:
None
"""
self.current_number += 1
def decrement_number(self):
"""Method to decrement the number.
Args:
None
"""
self.current_number -= 1
def clear_number(self):
"""Method to clear the number.
Args:
None
"""
self.current_number = 0

Now that the lone source code file is properly commented, we need to edit the Sphinx configuration file (‘…/docs/source/conf.py’) to be able to find out source code. Uncomment the following line from ‘…/docs/source/conf.py’ and make it point to the top-level directory in your project:

# 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('../..'))

OK, everything should be configured to actually generate the auto-documentation. In the ‘…/docs/’ folder, run:

$ sphinx-apidoc -f -o source/ ../python_documentation/
Creating file source/python_documentation.rst.
Creating file source/modules.rst.

This command created the applicable *.rst files for your project. Now, let’s make some nice looking HTML files:

$ make html

NOTE: This may require using ‘sudo’ to run this command as it is dependent on using the Xcode/iOS license.

This command generates a series of HTML files in the ‘…/docs/build/html/’ folder. In your favorite web browser, open the ‘index.html’ file in that folder. It should look like:

This is the main page for the auto-generated documentation for your project! Very cool! Clicking on ‘Index’ displays:

Finally, clicking on ‘BasicClass’ should the documentation for the class in your source code:

Conclusion:

This blog post provides an introduction to using Sphinx for a simple python project. Further references for continuing to learn about Sphinx and auto-generating your documentation are below.

Good References:

Blog Post from Giselle Zeno on using Sphinx:
<http://gisellezeno.com/tutorials/sphinx-for-python-documentation.html>

Blog Post from Marina Mele on documenting a Django project:
<http://www.marinamele.com/2014/03/document-your-django-projects.html>

Examples of Documenting Python Source Code for Sphinx:
<http://pythonhosted.org/an_example_pypi_project/sphinx.html>

Restructured Test (rest) and Sphinx CheatSheet:
<http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>

PEP-8 Style Guide for Python Code:
<https://www.python.org/dev/peps/pep-0008/>


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK