Package Documentation Files

Documenting your project is important if you want anyone else to use it. Documentation is done using a markup language that is then converted into HTML for your website.

To convert from a markup language to HTML we use a tool called Sphinx. Sphinx is a popular tool for creating web documentation for Python projects. It is part of a larger group of tools known as Static Site Generators. You can see a list of top static site generators at StaticGen.

Markdown (.md) and RestructuredText (.rst) - Static sites are normally written using either markdown or restructured text. Markdown is more popular in the whole eco-system of markup. RestructuredText is more popular for Python documentation. Restructured Text also allows inclusion of external files, which is GREAT for maintaining code samples. See examples of this at:

http://arcade.academy/examples

To get started with Sphinx, there’s a sphinx-quickstart command that can build out some of the files to get started. Personally, I find it easier to start with an old project and copy/modify from there.

Building API Docs From Code

Sphinx can pull documentation stored in comments from Python files. If the Python code looks like this:

Documented Python Code Listing
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def my_function():
    """
    Sample function that prints Hi
    """
    print("Hi")


def my_addition_function(a: int, b: int):
    """
        Sample function that adds two integers.

        Our documentation starts off with a one-line sentence. We can follow it up
        with multiple lines that give a more complete description.

        :param int a: First number to add.
        :param int b: Second number to add.

        :return: The two numbers added together.
        :rtype: int
        :raises: None

        Then we can follow it up with an example:

        :Example:

            >>> result = my_addition_function(10, 15)
            >>> print(result)

        .. note::
            This is just a silly example. Don't really use this function to add
            numbers.

    """
    return a + b

Then, in the restructured text file add code like the following:

.. automodule:: pypi_package_example
    :members:
    :undoc-members:
    :inherited-members:
    :show-inheritance:

And finally get output that looks like this: API

Note how it also links to the source of the code!

Read The Docs

Do you have an open-source project and don’t want to spend a lot of time hosting a website and keeping everything up-to-date? ReadTheDocs will take any GitHub project and automatically build a website for you using Sphinx. They will inject some ads into it to help pay for it.

ReadTheDocs supports custom URLs. They also support webhooks that will auto-build the documentation every time you push a new version to GitHub.

Files and Directories for Documentation

  • /doc/ Put your documentation in this directory
  • /doc/index.rst This is your main landing page
  • /doc/_static This directory will be included in your main project. I use it for a custom css file.
  • /doc/images It is a good idea to keep images separate from content.
  • /pypi_package_example/examples If you want example code, I suggest putting it in a subdirectory to your project. Don’t put it in the doc directory. This makes it easy to run your example with a command like:
python -m pypi_package_example/examples/my_example