Python source code documentation tools are programs used by developers to produce high-quality documentation for the code they write. These tools also highlight syntax rules, best coding conventions and style sheets. In short, python documentation tools help you construct clean and verbose code that is easy to understand by the programming community.
Have you ever written a python code, and wondered how much you should document each of the methods and functions? If you have documented your code before, did you prefer using python docx source code or did you use a custom style of documenting? These are just some of the questions that we would like to answer in the next few paragraphs.
This is the main documentation for Python source code documentation tools used to generate a complete set of documentation from your source code. These will walk you through the steps to run the various applications, including configuration.
Source code documentation is an important part of any programming project. It helps readers understand how the code works, even when the comments within the source code aren’t particularly useful. This article will introduce you to a variety of source code documentation tools that can be used with Python.
Pros of creating good documentation:
- Increases information exchange between team members— this single reason is just so powerful!
- Decreases onboarding time of new members
3. Helps to organize big projects (helps to see the big picture)
4. Increases team member awareness of how the whole project is organized
5. Increases development speed — finding information is faster and thus development is faster
6. Promotes standards and consistency
Generated Docs
The intent of pycco is to generate a two-column document with comments on the left hand side, aligned with the subsequent code on the right hand side. So, calling pycco on our models.py class that has no comments yet will generate a page that looks like this:
You’ll notice that the left hand column (where the comments should be) is simply blank and the right hand side shows the code. We can change models.py by adding a docstring to get more interesting documents by adding the following code to models.py.
from django.db import models
# === Models for Todos app ===
class ListItem(models.Model):
"""
The ListItem class defines the main storage point for todos.
Each todo has two fields:
text - stores the text of the todo
is_visible - used to control if the todo is displayed on screen
"""
text = models.CharField(max_length=300)
is_visible = models.BooleanField()With the code snippet above, pycco finds the line:
# === Models for Todos app ===
And then generates a header in the documentation.
The docstring:
"""
The ListItem class defines the main storage point for todos.
Each todo has two fields:
text - stores the text of the todo
is_visible - used to control if the todo is displayed on screen
"""
Pycco uses the docstring to generate the documentation. The end result after running pycco again will be:
As you can see the documentation on the left is nicely aligned with the code on the right. This makes it really easy to review the code and understand whats going on.
Pycco also recognizes single line comments in the code that start with a # to generate documentation.
Make It Fancy
But pycco doesn’t stop there. It also allows for custom formatting of comments using markdown. As an example let’s put some comments in the views.py file. For starters let’s just put a docstring at the top of views.py:
"""
All the views for our todos application
Currently we support the following 3 views:
1. **Home** - The main view for Todos
2. **Delete** - called to delete a todo
3. **Add** - called to add a new todo
"""
from django.http import HttpResponse
from django.shortcuts import render_to_response
from django.template import RequestContext
from todos.models import ListItem
def home(request):
items = ListItem.objects.filter(is_visible=True)
return render_to_response('home.html', {'items': items}, context_instance = RequestContext(request))
# ... code omitted for brevity ...
This will produce a report like this:
We can also add links between files and even inside the same file. Links can be added by using [[filename.py]] or [[filename.py#section]] and they will render like a link with the file name. Let’s update views.py to add some links at the end of each item in the list:
"""
All the views for our todos application
Currently we support the following 3 views:
1. **Home** - The main view for Todos (jump to section in [[views.py#home]] )
2. **Delete** - called to delete a todo ( jump to section in [[views.py#delete]] )
3. **Add** - called to add a new todo (jump to section in [[views.py#add]])
"""
from django.http import HttpResponse
from django.shortcuts import render_to_response
from django.template import RequestContext
# defined in [[models.py]]
from todos.models import ListItem
# === home ===
def home(request):
items = ListItem.objects.filter(is_visible=True)
return render_to_response('home.html', {'items': items}, context_instance = RequestContext(request))
# === delete ===
def delete(request):
# ... code omitted for brevity ...
As you can tell there are two components to making the link. First, we have to define a section in our documentation. You can see we have defined the home section with the code # === home ===. Once the section is created we can link to it with the code [[views.py#home]]. Also we inserted a link to the models documentation file with the code:
# defined in [[models.py]]
The end result is documentation that looks like this:
Keep in mind that because pycco allows for markup syntax you can also use full blown html. So go crazy 🙂
reStructuredText
Most Python documentation is written with reStructuredText. It’s like Markdown, but with all the optional extensions built in.
The reStructuredText Primer and the reStructuredText Quick Reference should help you familiarize yourself with its syntax.
Code Documentation Advice
Comments clarify the code and they are added with purpose of making the code easier to understand. In Python, comments begin with a hash (number sign) (#).
In Python, docstrings describe modules, classes, and functions:
def square_and_rooter(x):
"""Return the square root of self times self."""
...
In general, follow the comment section of PEP 8#comments (the “Python Style Guide”). More information about docstrings can be found at PEP 0257#specification (The Docstring Conventions Guide).
Commenting Sections of Code
Do not use triple-quote strings to comment code. This is not a good practice, because line-oriented command-line tools such as grep will not be aware that the commented code is inactive. It is better to add hashes at the proper indentation level for every commented line. Your editor probably has the ability to do this easily, and it is worth learning the comment/uncomment toggle.
Docstrings and Magic
Some tools use docstrings to embed more-than-documentation behavior, such as unit test logic. Those can be nice, but you won’t ever go wrong with vanilla “here’s what this does.”
Tools like Sphinx will parse your docstrings as reStructuredText and render it correctly as HTML. This makes it very easy to embed snippets of example code in a project’s documentation.
Additionally, Doctest will read all embedded docstrings that look like input from the Python commandline (prefixed with “>>>”) and run them, checking to see if the output of the command matches the text on the following line. This allows developers to embed real examples and usage of functions alongside their source code. As a side effect, it also ensures that their code is tested and works.
def my_function(a, b):
"""
>>> my_function(2, 3)
6
>>> my_function('a', 3)
'aaa'
"""
return a * b
Docstrings versus Block comments
These aren’t interchangeable. For a function or class, the leading comment block is a programmer’s note. The docstring describes the operation of the function or class:
# This function slows down program execution for some reason.
def square_and_rooter(x):
"""Returns the square root of self times self."""
...
Unlike block comments, docstrings are built into the Python language itself. This means you can use all of Python’s powerful introspection capabilities to access docstrings at runtime, compared with comments which are optimized out. Docstrings are accessible from both the __doc__ dunder attribute for almost every Python object, as well as with the built in help() function.
While block comments are usually used to explain what a section of code is doing, or the specifics of an algorithm, docstrings are more intended towards explaining other users of your code (or you in 6 months time) how a particular function can be used and the general purpose of a function, class, or module.
Writing Docstrings
Depending on the complexity of the function, method, or class being written, a one-line docstring may be perfectly appropriate. These are generally used for really obvious cases, such as:
def add(a, b):
"""Add two numbers and return the result."""
return a + b
The docstring should describe the function in a way that is easy to understand. For simple cases like trivial functions and classes, simply embedding the function’s signature (i.e. add(a, b) -> result) in the docstring is unnecessary. This is because with Python’s inspect module, it is already quite easy to find this information if needed, and it is also readily available by reading the source code.
In larger or more complex projects however, it is often a good idea to give more information about a function, what it does, any exceptions it may raise, what it returns, or relevant details about the parameters.
For more detailed documentation of code a popular style used, is the one used by the NumPy project, often called NumPy style docstrings. While it can take up more lines than the previous example, it allows the developer to include a lot more information about a method, function, or class.
def random_number_generator(arg1, arg2):
"""
Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
int
Description of return value
"""
return 42
The sphinx.ext.napoleon plugin allows Sphinx to parse this style of docstrings, making it easy to incorporate NumPy style docstrings into your project.
At the end of the day, it doesn’t really matter what style is used for writing docstrings; their purpose is to serve as documentation for anyone who may need to read or make changes to your code. As long as it is correct, understandable, and gets the relevant points across then it has done the job it was designed to do.
The difference between Python comments and docstrings
You all must have got an idea about Python docstrings but have you ever wondered what is the difference between Python comments and docstrings. Let’s have a look at them.
Python Comments are the useful information that the developers provide to make the reader understand the source code. It explains the logic or a part of it used in the code. It is written by using # symbol.
Example:
# Python program to demonstrate commentsprint("GFG") |
Output:
GFG
Whereas Python Docstrings as mentioned above provides a convenient way of associating documentation with Python modules, functions, classes, and methods.
This article is contributed by Mayank Agrawal. If you like GeeksforGeeks and would like to contribute, you can also write an article using contribute.geeksforgeeks.org or mail your article to contribute@geeksforgeeks.org. See your article appearing on the GeeksforGeeks main page and help other Geeks.
Please write comments if you find anything incorrect, or you want to share more information about the topic discussed above.
Three types of autogenerated documentation:
By autogenerated I mean documentation which is built with some tool (maybe cli) and the output is instantly browsable (in a form of a web page, a pdf etc..). We can distinguish 3 types of these:
- fully automatic — no need to do anything manually
- semi-automatic — it works without doing anything manually, but it can be better when you put in some extra effort
- manual — you write the documentation by yourself, the output webstie/pdf is generated automatically
Conclusion
Every programmer knows how hard it is to write clean and consistent code. If you do not take the time to write and document your code, you will be wasting a lot of time going back to fix bugs later and will make your job much harder.
This is actually a little bit competitive. There are some other options for a tool that can auto-generate Python documentation, including epydoc, pdoc and pydoc. Each of these tools has its own features and quirks, so be sure to check each one out individually to see what works best for you