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:
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