Python Code Documentation Tools

Python Code Documentation Tools

by

Python doc generator tools are used to convert python source code into an organized, searchable, consistent and pretty document. Docstrings (documentation strings — also known as docstrings) are included in most Python files to help others understand the code. These comments make it easier to find information about what a function or class does, how certain parameters work, etc. If you don’t have time to write documentation by hand and not sure what should be written, then use doc generator tool to generate docs through code comments (docstring).

Python, the interpreted high-level programming language designed with a focus on code readability and built-in multithreading capabilities, is one of the world’s most popular programming languages. It is also very easy to use as it provides libraries that enable developers to write programs using fewer lines of code with more functionality. Python’s readable code encourages developers to spend less time debugging and updating their software, and more time writing new programs. If you are curious about the ways of Python documentation and Python code documentation generator, read on for more details.

Python code documentation isn’t the easiest thing to write. There are many things that can make your documentation get out of sync with the actual code and it gets hard to keep track of who contributed what and in what version. Wouldn’t it be great if there was a tool to help you create python documentation from code?

Python documentation tools allow you to automatically extract technical documentation from your Python source code. They can also be used for generating UML class diagrams from code. This guide will introduce the most popular Python documentation generators.

Generating Code Documentation with Pycco

As developers we love to write code, and even though it makes sense to us at the time, we must think of our audience. Someone has to read, use, and/or maintain said code. It could be another developer, a customer, or our future selves, three months later.

Even a beautiful language like Python can be difficult to understand at times. So as good programming citizens who care deeply about our fellow coders (or more likely because our boss wants us to) we should write some documentation.

But there are rules:

  1. Writing documentation must not suck (i.e. we cannot use MS Word).
  2. Writing documentation must be as effortless as possible.
  3. Writing documentation must not require us to leave our favorite text editor / IDE.
  4. Writing documentation must not require us to do any formatting or care at all about the final presentation.

This is where Pycco comes in:

“Pycco” is a Python port of Docco: the original quick-and-dirty, hundred-line-long, literate-programming-style documentation generator. It produces HTML that displays your comments alongside your code. Comments are passed through Markdown and SmartyPants, while code is passed through Pygments for syntax highlighting.

So basically that means that Pycco can auto-generate decent looking code documentation for us. Pycco also adheres to the four rules of code documentation stated above. So what’s not to love? Let’s jump into to some examples of how to use it.

For this article, I’ve started off with a simple TODO app written in Django, which you can grab from the repo. The app allows a user to add items to a list and delete them upon completion. This app probably isn’t going to win me a Webby, but it should serve the purpose for this article.

Please note, the files in the repo already contain the final code, already documented. You can still create the seperate documented files though, so feel free to clone the repo and follow along with me.

Project Setup

Clone the repo:

$ git clone git@github.com:mjhea0/django-todo.git

Setup virtualenv:

$ cd django-todo
$ virtualenv --no-site-packages venv
$ source venv/bin/activate

Install the requirements:

$ pip install -r requirements.txt

Sync the database:

$ cd todo
$ python manage.py syncdb

Generate some docs

Getting started is simple:

$ pip install pycco

Then to run it you can use a command like:

$ pycco todos/*.py

Note this way you can specify individual files or a directory of files. Executing the above command on our TODO repo generates the following outcome:

pycco = todo/todos/__init__.py -> docs/__init__.html
pycco = todo/todos/models.py -> docs/models.html
pycco = todo/todos/tests.py -> docs/tests.html
pycco = todo/todos/views.py -> docs/views.html

In other words, it generates the html files (one for each python file) and dumps them all in the “docs” directory. For larger projects you may want to use the -p option that will preserve the original file paths.

Readability is a primary focus for Python developers, in both project and code documentation. Following some simple best practices can save both you and others a lot of time.

Project Documentation

A README file at the root directory should give general information to both users and maintainers of a project. It should be raw text or written in some very easy to read markup, such as reStructuredText or Markdown. It should contain a few lines explaining the purpose of the project or library (without assuming the user knows anything about the project), the URL of the main source for the software, and some basic credit information. This file is the main entry point for readers of the code.

An INSTALL file is less necessary with Python. The installation instructions are often reduced to one command, such as pip install module or python setup.py install, and added to the README file.

A LICENSE file should always be present and specify the license under which the software is made available to the public.

A TODO file or a TODO section in README should list the planned development for the code.

A CHANGELOG file or section in README should compile a short overview of the changes in the code base for the latest versions.

Project Publication

Depending on the project, your documentation might include some or all of the following components:

  • An introduction should give a very short overview of what can be done with the product, using one or two extremely simplified use cases. This is the thirty-second pitch for your project.
  • A tutorial should show some primary use cases in more detail. The reader will follow a step-by-step procedure to set-up a working prototype.
  • An API reference is typically generated from the code (see docstrings). It will list all publicly available interfaces, parameters, and return values.
  • Developer documentation is intended for potential contributors. This can include code convention and general design strategy of the project.

Sphinx

Sphinx is far and away the most popular Python documentation tool. Use it. It converts reStructuredText markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages, and plain text.

There is also great, free hosting for your Sphinx docs: Read The Docs. Use it. You can configure it with commit hooks to your source repository so that rebuilding your documentation will happen automatically.

When run, Sphinx will import your code and using Python’s introspection features it will extract all function, method, and class signatures. It will also extract the accompanying docstrings, and compile it all into well structured and easily readable documentation for your project.

Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods.

It’s specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, the docstring should describe what the function does, not how.

What should a docstring look like?

  • The doc string line should begin with a capital letter and end with a period.
  • The first line should be a short description.
  • If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description.
  • The following lines should be one or more paragraphs describing the object’s calling conventions, its side effects, etc.

Declaring Docstrings: The docstrings are declared using ”’triple single quotes”’ or “””triple double quotes””” just below the class, method or function declaration. All functions should have a docstring.

Accessing Docstrings: The docstrings can be accessed using the __doc__ method of the object or using the help function.
The below examples demonstrates how to declare and access a docstring.

Example 1: Using triple single quotes

def my_function():    '''Demonstrates triple double quotes    docstrings and does nothing really.'''       return None  print("Using __doc__:")print(my_function.__doc__)  print("Using help:")help(my_function)

Output:

Using __doc__:
Demonstrates triple double quotes
    docstrings and does nothing really.
Using help:
Help on function my_function in module __main__:

my_function()
    Demonstrates triple double quotes
    docstrings and does nothing really.

Example 2: Using triple double quotes

def my_function():    """Demonstrates triple double quotes    docstrings and does nothing really."""       return None  print("Using __doc__:")print(my_function.__doc__)  print("Using help:")help(my_function)

Output:

Using __doc__:
Demonstrates triple double quotes
    docstrings and does nothing really.
Using help:
Help on function my_function in module __main__:

my_function()
    Demonstrates triple double quotes
    docstrings and does nothing really.

One-line Docstrings

As the name suggests, one line docstrings fit in one line. They are used in obvious cases. The closing quotes are on the same line as the opening quotes. This looks better for one-liners.
For example:

def power(a, b):    """Returns arg1 raised to power arg2."""       return a**b  print(power.__doc__)

Output:

Returns arg1 raised to power arg2.

Multi-line Docstrings

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be on the same line as the opening quotes or on the next line.
The example below shows a multi-line docstring.

def my_function(arg1):    """    Summary line.      Extended description of function.      Parameters:    arg1 (int): Description of arg1      Returns:    int: Description of return value      """      return arg1  print(my_function.__doc__)

Output:

    Summary line.
    Extended description of function.
    Parameters:
    arg1 (int): Description of arg1

    Returns:
    int: Description of return value

Indentation in Docstrings

The entire docstring is indented the same as the quotes at its first line. Docstring processing tools will strip a uniform amount of indentation from the second and further lines of the docstring, equal to the minimum indentation of all non-blank lines after the first line. Any indentation in the first line of the docstring (i.e., up to the first newline) is insignificant and removed. Relative indentation of later lines in the docstring is retained.

Docstrings in Classes

Let us take an example to show how to write docstrings for a class and its methods. help is used to access the docstring.

class ComplexNumber:    """    This is a class for mathematical operations on complex numbers.          Attributes:        real (int): The real part of complex number.        imag (int): The imaginary part of complex number.    """      def __init__(self, real, imag):        """        The constructor for ComplexNumber class.          Parameters:           real (int): The real part of complex number.           imag (int): The imaginary part of complex number.           """      def add(self, num):        """        The function to add two Complex Numbers.          Parameters:            num (ComplexNumber): The complex number to be added.                  Returns:            ComplexNumber: A complex number which contains the sum.        """          re = self.real + num.real        im = self.imag + num.imag          return ComplexNumber(re, im)  help(ComplexNumber)  # to access Class docstringhelp(ComplexNumber.add)  # to access method's docstring

Output:

Help on class ComplexNumber in module __main__:

class ComplexNumber
 |  This is a class for mathematical operations on complex numbers.
 |  
 |  Attributes:
 |          real (int): The real part of complex number.
 |          imag (int): The imaginary part of complex number.
 |  
 |  Methods defined here:
 |  
 |  __init__(self, real, imag)
 |      The constructor for ComplexNumber class.
 |      
 |      Parameters:
 |      real (int): The real part of complex number.
 |      imag (int): The imaginary part of complex number.
 |  
 |  add(self, num)
 |      The function to add two Complex Numbers.
 |      
 |      Parameters:
 |              num (ComplexNumber): The complex number to be added.
 |      
 |      Returns:
 |              ComplexNumber: A complex number which contains the sum.

Help on method add in module __main__:

add(self, num) unbound __main__.ComplexNumber method
    The function to add two Complex Numbers.
    
    Parameters:
            num (ComplexNumber): The complex number to be added.
    
    Returns:
            ComplexNumber: A complex number which contains the sum.

Tips for technical documentation writing

Add a quick start option

When onboarding a new team member to work with your code, you want to get them up to speed quickly, but you don’t have time to sit over their shoulder stepping them through the documentation. This is where a comprehensive collection of related resources can be invaluable.

Give your dev team quick start page or bullet points that link to all the relevant resources.

The benefits:

  • It significantly improves the user experience for your reader
  • Provides context by giving them a high-level overview of the documentation
  • Allows them to easily return to related resources when it’s time to review them
  • Makes the content easier to consume by breaking into chunks

To create a more sequenced and organized learning experience for new developers, take a look at Swimm Playlists, which allow you to group numerous types of related resources in a single location for your readers to work through in the order you choose. Swimm also has created documentation templates as a quick start option to help you get started.

Help readers find the documentation

Be sure to keep technical documentation in a centralized (preferably cloud-based) location, organized into logical folders or buckets. If you’re using Word documents, PDFs, or Google Docs, ensure that you give viewing rights to the people who need to access them.

Of course, if you use Swimm’s documentation platform, you’ll find docs when you need them in your IDE and access them right next to the code they refer to.

If nobody can find or access your documentation, it begs the question as to the point of writing it in the first place.

Document code changes

Document any changes to your code. Be sure to include new features, bug fixes, deprecated/sunset features. The documentation should explain the why: why the code changes and you should write down whatever it is that you and your dev team will want to remember next time.

Documentation will help keep your codebase free of spaghetti code and dreaded technical debt.

Get documentation feedback

Even if you don’t have an “official” review workflow, share your documentation with your team and get their feedback.

A second set of eyes will help you recognize that what may be crystal clear to you might be not clear at all for another developer.

Conclusion

Documentation is important to be developed every time when you build a python program, module, library. Python documentation generator is one of the important tools to be developed of python code documentation, which could help you generate the documentation of your python source code automatically.

Documenting your code is an important part of coding professionally. The documentation section of the python standard library provides all the documentation tools you will need, both for interactive help and docstrings.

Leave a Comment