Step by Step Fundamentals: Code Autodocumentation

0
36


Generate flawless documentation of Python code utilizing Sphinx

0*8ygNBT0T0gWZD7Wi
Picture by Dustin Humes on Unsplash

You’ll be able to construct lovely, standardised and stylised documentation utilizing simply the docstrings in just a few easy steps.

A Knowledge Scientist holds many obligations when engaged on a venture, and one that’s often left till the final minute is documentation. Maybe you’re diligent with writing docstrings for lessons and features (nicely achieved!) — however ought to that be the resting place of your documentation?

In my view, documentation ought to sit independently out of your code. Your group (otherwise you in just a few months time) shouldn’t should trawl by means of a whole lot of strains of code in your python modules to know what’s occurring. You’ll be able to construct lovely, standardised and stylised documentation utilizing simply the docstrings in just a few easy steps and make your venture communicate for itself.

On this article, I’ll give attention to utilizing the Sphinx framework for autodocumenting python modules. I’ll even be utilizing the Cookiecutter Knowledge Science venture template in Visible Studio Code (VS Code) as a consequence of its seamless integration with Sphinx and standardised listing construction. While the official sphinx tutorial documentation is a good useful resource for these eager to take a deep dive into this matter, my purpose for this text is to be a useful ‘fast begin’ information to take you thru the important thing steps. Get pleasure from 🙂

A word on docstrings

The important thing to good documentation is docstrings. These are the remark blocks that sit inside every class, class technique and performance that describe the character of the code, together with the inputs, outputs and raised errors. There are three core docstring codecs. These are Google, reStructuredText (reST) and NumPy. All of them include the identical data, the one distinction is that they’re formatted in another way. You’ll be able to see examples of every docstring format right here.

I’ll be utilizing the Google docstring format as it’s straightforward to learn and takes up much less area than the others. The under code block is a typical instance of a Google docstring:

"""Description of the operate, class or technique and so on.

Args:
varA (str): Description of varA
varB (bool): Description of varB

Returns:
checklist: Description of returned checklist

Raises:
ValueError: Description of raised error
"""

High tip. obtain the ‘autoDocstring — Python Docstring Generator’ in VS Code to routinely generate a docstring once you sort three double citation marks (i.e. the beginning of a docstring). Make sure you end writing the operate earlier than producing the docstring so that every one inputs/outputs/errors get included within the docstring template that will get generated for you!

Let’s transfer on to creating the documentation!

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

Contents of demo.py module to be documented. Snapshot taken utilizing CodeSnap extension in VS Code.

1. Setup

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

possibility A — set up Cookiecutter

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

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 venture might be created. The Sphinx framework might be saved within the /docs listing of your venture.

possibility B — Sphinx quickstart

If the Cookiecutter template doesn’t take your fancy, you may create your personal venture 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 might be some recordsdata that seem within the documentation listing in your venture. 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 on your documentation. You will discover extra data on the index.rst file right here. The getting-started.rst and instructions.rst recordsdata are prompt templates on your documentation. You’ll be able to 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 once you’re able to make the documentation.

1*8szuZ0RgfOjPfERLLs0RzA
Default Sphinx recordsdata put in

3. Conf.py file

The configuration file is the place the magic occurs. This file is used throughout the construct course of and so it’s essential that you’ve got this arrange appropriately. Beneath 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 venture. Therefore I’ll change the os.path.abspath to the look in /src listing which is situated within the guardian folder of the conf.py file. You’ll be able to 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
'..' # guardian path of conf.py
'../..' # guardian of the guardian path of conf.py
"""
1*VYvRYBBBYXOiPCcnDw QOA
The relative location of the listing containing the python modules to the documentation folder. On this instance, ‘demo.py’ is the module to be documented, situated within the src/knowledge/ listing.

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 elective and you may have some enjoyable exploring the totally different extensions accessible right here. Listed below 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 have got a variety of docstrings. Word. you will want 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 — gives a abstract of what number of lessons/features and so on have docstrings. Good protection signifies {that a} codebase is nicely defined.

Right here’s find out how to embody these extensions within the conf.py file (line 29 in my setup):

#  add within the extension names to the empty checklist 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 sort of clear, though you might choose to mess around with totally different choices by altering the ‘html_theme’ variable (line 94 in my setup) from ‘default’ to one of many normal theme choices or some third social gathering 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 will want to pip set up any non-standard (third social gathering) themes.

4. Make the html pages

Now that your conf.py file is ready 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 simply specified within the conf.py file. There are some elective parameters to incorporate when utilizing the apidoc command which yow will discover within the documentation, however I used the next template:

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

sphinx-apidoc -f -o output_dir module_dir/

-f (power overwriting any current generated recordsdata).

-o output_dir (listing to put 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 must be newly generated .rst recordsdata within the docs folder.

1* ANTC6n6qDOnNrtY2mcFhg
Contents of documentation folder after operating sphinx-apidoc command to generate .rst recordsdata

Discover that two new .rst recordsdata have been generated: knowledge.rst and modules.rst. Along with modules.rst, a .rst file might be generated for every listing that incorporates not less than one python module. In my instance, knowledge.rst is generated as I’ve saved my demo.py file within the src/knowledge listing. In case you 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 might be generated. Word. These recordsdata don’t include the scraped documentation simply but, they only include the knowledge 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 may 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. Be sure 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’ll be able to delete them from this file if you do not need to generate html pages (though a ‘getting-started’ web page might be an excellent thought!)

1*BqlWf1Riq6tEj7fbYEbbqA
Contents of the index.rst file. I’ve added in ‘modules’ in order that the modules.rst file is used within the html era course of.

Make html recordsdata

Now we are able to 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’ll be able to preview these in VS code in case you 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. if you’re utilizing home windows powershell terminal (somewhat than cmd), use the next syntax:

.make.bat html

High tip. if a warning arises when utilizing the make html command that states ‘autodoc: did not import module’, that is almost definitely as a consequence of autodoc not with the ability to discover your modules because the sys.path has not been configured appropriately in conf.py. Be sure this factors to the listing the place your python modules are situated.

Modifying html recordsdata

In the event you want to edit your docstrings and replace your html recordsdata with the modifications, 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 totally different themes seen within the photos under; ‘default’ (left picture) and ‘Learn the Docs’ (proper picture). The content material is equivalent however the appear and feel are totally different. Let’s be aware of the core options:

  • Navigation bar on left hand facet
  • A abstract of all lessons or features belonging to the module in tables on the high of the web page (due to the ‘autodocsumm’ extension)
  • Detailed checklist of docstring parts for all features and lessons under the abstract
1*AZX7Ig8X2IbnwLr1ksX0Eg
1*KcRKEAoZHHVXiM6HmGmjLQ
Examples of documentation html pages for a pattern python module utilizing default theme (left picture) and the learn the docs theme (proper picture), generated utilizing Sphinx.

When you’ve created the html pages, you’ll discover a wide range of hierarchical html pages might be generated. These will embody a house web page and pages for every package deal and module. Take a look across the pages to familiarise your self with their construction and browse the official documentation to see how one can customise them additional.

For instance, in case you wished to have the ability to see the uncooked code of every operate within the documentation, add the extension ‘sphinx.ext.viewcode’ to the conf.py file. It will add a hyperlink subsequent to every operate or class technique which is able to reveal the uncooked code to permit for simple interrogation with out having to delve into the codebase.

Closing ideas

And there we have now it. Easy and exquisite documentation of your Python modules made in just a few straightforward steps utilizing Sphinx! I hope you have got loved studying about autodocumentation and discover it to be a useful gizmo to implement in your tasks. In case you have any helpful ideas then be at liberty so as to add a remark 🙂

stat?event=post


Step by Step Fundamentals: Code Autodocumentation was initially printed in In the direction of Knowledge Science on Medium, the place individuals are persevering with the dialog by highlighting and responding to this story.



Supply hyperlink

LEAVE A REPLY

Please enter your comment!
Please enter your name here