For the aim of this demo, I’ve created a python module demo.py which incorporates a category and three primary features (all annotated with docstrings excluding one perform). It’s this module that I’ll be constructing documentation for on this article. The contents of this demo.py module is beneath:

1. Setup

Very first thing is to get all the things setup. You’ll want to put in VS Code and setup a brand new challenge together with Sphinx. There are just a few choices right here. You may both a) arrange a brand new challenge utilizing Cookiecutter (the place the related Sphinx setup can be generated together with standardised directories) or b) create your personal challenge construction and set up sphinx individually.

choice A — set up Cookiecutter

Within the terminal, pip set up Cookiecutter after which create a brand new challenge:

pip set up cookiecutter
cookiecutter https://github.com/drivendata/cookiecutter-data-science

Subsequent, reply the questions that seem within the terminal window and your new challenge can be created. The Sphinx framework can be saved within the /docs listing of your challenge.

choice B — Sphinx quickstart

If the Cookiecutter template doesn’t take your fancy, you’ll be able to create your personal challenge construction from scratch and set up sphinx. It’s a good suggestion to make a documentation listing and set up sphinx there. Within the terminal:

mkdir docs
cd docs
pip set up sphinx
sphinx-quickstart

2. Understanding Sphinx folder construction

After you’ve put in Sphinx utilizing one of many choices above, there can be some recordsdata that seem within the documentation listing in your challenge. The conf.py file is the important thing configuration file which you’ll edit to make your documentation bespoke — extra element on this within the subsequent part. The index.rst file acts as a contents in your documentation. You could find extra info on the index.rst file right here. The getting-started.rst and instructions.rst recordsdata are urged templates in your documentation. You may take away these if mandatory. The make recordsdata (make.bat and Makefile) are used to truly make the documentation. You don’t must edit these however will name them within the terminal window if you’re able to make the documentation.

3. Conf.py file

The configuration file is the place the magic occurs. This file is used in the course of the construct course of and so it’s essential that you’ve got this arrange accurately. Under are some steps to modifying the conf.py file:

Uncomment the sys.path line (line 20 in my setup):

#  sys.path.insert(0,  os.path.abspath('.')) 

Change the pathway of the os.path.abspath to the relative location of the code you need documenting (relative to the conf.py file). For instance, the python modules that I would like documenting sits inside the src/ listing of my challenge. Therefore I’ll change the os.path.abspath to the look in /src listing which is situated within the mum or dad folder of the conf.py file. You may specify the relative location utilizing the . and / syntax:

sys.path.insert(0,  os.path.abspath('../src'))
"""
# you need to use the next syntax to specify relative places:
'.' # present path of conf.py
'..' # mum or dad path of conf.py
'../..' # mum or dad of the mum or dad path of conf.py
"""

Add within the related extensions. You’ll want so as to add in some extensions to the conf.py file to achieve additional performance when creating your documentation. These are all non-obligatory and you may have some enjoyable exploring the completely different extensions obtainable right here. Listed here are the 5 extensions that I like to recommend at minimal:

• sphinx.ext.autodoc — use documentation from docstrings
• autodocsumm — generate a tabular abstract of all docstrings on the high of the html web page by itemizing out the docstring summaries solely. Helpful when you might have a whole lot of docstrings. Word. you’ll need to pip set up autodocsumm within the terminal.
• sphinx.ext.napoleon — allows Sphinx to parse google docstrings
• sphinx.ext.viewcode — provides a hyperlink to a html web page containing the supply code for every module
• sphinx.ext.protection — offers a abstract of what number of courses/features and so forth have docstrings. Good protection signifies {that a} codebase is properly defined.

Right here’s the right way to embrace these extensions within the conf.py file (line 29 in my setup):

#  add within the extension names to the empty listing variable 'extensions'
extensions = [
'sphinx.ext.autodoc', 
'sphinx.ext.napoleon', 
'autodocsumm', 
'sphinx.ext.coverage'
]
# add on this line for the autosummary performance
auto_doc_default_options = {'autosummary': True}

Change the theme. The default theme of the documentation is kind of clear, though it’s possible you’ll desire to mess around with completely different choices by altering the ‘html_theme’ variable (line 94 in my setup) from ‘default’ to one of many customary theme choices or some third celebration choices. On this demo, I’ll present the default and Learn the Docs themes.

html_theme = 'sphinx_rtd_theme' # learn the docs theme. This variable is 'default' by default.

Word. you’ll need to pip set up any non-standard (third celebration) themes.

4. Make the html pages

Now that your conf.py file is about up and you’ve got wonderful docstrings in your code, we’re able to do some scraping and construct some html pages.

Generate .rst recordsdata of your python packages

These recordsdata are the precursor to the html pages and are the native format for Sphinx. These should be generated earlier than making the html recordsdata. You’ll use the sphinx.apidoc command, which makes use of the autodoc extension to find all python modules (e.g. any .py recordsdata) inside the sys.path location that you just specified within the conf.py file. There are some non-obligatory parameters to incorporate when utilizing the apidoc command which you’ll find within the documentation, however I used the next template:

Word. within the terminal, change listing to the foundation of the challenge to run the next code.

sphinx-apidoc -f -o output_dir module_dir/

-f (power overwriting any present generated recordsdata).

-o output_dir (listing to position the output recordsdata. If it doesn’t exist, it’s created). Word. exchange ‘output_dir’ with a listing title of your selection. I set mine to the /docs listing.

module_dir (location of python packages to doc)

After operating this command, there needs to be newly generated .rst recordsdata within the docs folder.

Discover that two new .rst recordsdata have been generated: knowledge.rst and modules.rst. Along with modules.rst, a .rst file can be generated for every listing that incorporates at the least one python module. In my instance, knowledge.rst is generated as I’ve saved my demo.py file within the src/knowledge listing. You probably have a number of directories of python modules inside the location you laid out in sys.path within the conf.py file, then a number of .rst recordsdata can be generated. Word. These recordsdata don’t comprise the scraped documentation simply but, they simply comprise the data required for autodoc to make the html recordsdata within the subsequent step.

Edit index.rst file

Keep in mind, index.rst acts as a contents web page so we should edit this file to incorporate all python modules we wish documenting. Fortunately, the modules.rst references the supply location of all python modules recognized within the sys.path, so you’ll be able to merely add this file to index.rst.

To do that, open the index.rst file and add ‘modules’ beneath the toctree (desk of contents tree) part. Ensure there’s a line in between the :maxdepth: parameter and the names of the the .rst recordsdata.
Word. ‘getting-started’ and ‘instructions’ will already be within the index.rst file. You may delete them from this file if you do not need to generate html pages (though a ‘getting-started’ web page might be a good suggestion!)

Make html recordsdata

Now we will use the make recordsdata in your documentation listing to construct the html recordsdata. These recordsdata will seem within the _build/html/ listing inside your documentation folder. You may preview these in VS code if you happen to obtain the ‘HTML Preview’ extension.

Change listing to the place the make.bat file is situated and run the next command in cmd terminal:

make html

Word. in case you are utilizing home windows powershell terminal (quite than cmd), use the next syntax:

.make.bat html

Prime tip. if a warning arises when utilizing the make html command that states ‘autodoc: didn’t import module’, that is probably resulting from autodoc not having the ability to discover your modules because the sys.path has not been configured accurately in conf.py. Ensure this factors to the listing the place your python modules are situated.

Enhancing html recordsdata

If you happen to want to edit your docstrings and replace your html recordsdata with the adjustments, then you are able to do so utilizing the next command:

make clear html

Let’s check out our documentation!

As I discussed above, I’ve created some documentation of my python module demo.py in two completely different themes seen within the pictures beneath; ‘default’ (left picture) and ‘Learn the Docs’ (proper picture). The content material is similar however the appear and feel are completely different. Let’s pay attention to the core options:

• Navigation bar on left hand aspect
• A abstract of all courses or features belonging to the module in tables on the high of the web page (because of the ‘autodocsumm’ extension)
• Detailed listing of docstring elements for all features and courses beneath the abstract