This is Day 19 of the #100DaysOfPython challenge.
This post will use the
pydoc module from the standard library to to explore how we can navigate documentation as well as create our own.
The code can be found on my GitHub repo.
Let’s create the
hello-pydoc directory and set up the required files.
At this stage, we have our files sorted and we can start to write some code.
Exploring PyDoc from the command line
PyDoc is a tool that allows us to explore the documentation of a module.
As a simple starter, we can use PyDoc to explore the documentation of the
datetime module from the command line.
To do so, we can run
python -m pydoc [module] and we should see the output based on the doc strings for each of the functions in the module.
Let’s explore this for the
datetime module. From the command line, we can run the following command:
When you run the command, it opens up the documentation for the
datetime module that can be traversed in the command-line.
It gives us information on the following:
| Heading | Description | | — — — — — — — | — — — — — — — — — — — — — — — — — — — — — — — | |
NAME | The name of the module. | |
FILE | The file that the module is defined in. | |
MODULE DOCS | The link to the documentation for the module. | |
CLASSES | The classes defined in the module. |
We can search within the docs by using the
? operator followed by a search term.
For example, in my previous blog post
Datetime in Python, we heavily relied upon the
To search for that documentation, I can run
/ followed by
now and one of the search results will return the following:
Tip: after searching, you can use the
nkey to navigate to the next result.
The above documentation tells us that the
now function returns a
datetime object with the timezone's local time and date (with an optional argument of the timezone).
Given this, we know that we could can the function both with and without an argument:
If we go searching for the synonymous function
utcnow, we can see the following:
This tells us that there are no arguments but the returned value is a
datetime object with the timezone of UTC.
Now that we know the basics of searching PyDoc, let’s now document our
Writing our own documented code
We can write and search for our own
To demonstrate, add the following code to
docstring is a string that is used to document the function and is denoted as the comment between lines 2 and 10 of the code above.
Tip: if you use VSCode, check out the
Once we have that code in place, it is enough to view our own documentation for the module!
Exploring our documented code
We can run
python -m pydoc src.math and we should see the output of the
How easy was that!
Viewing PyDoc in the browser
If we run
pydoc -h, we see the following:
This gives us a list of the options that we can use to view our own documentation.
First of all, we will use the
pydoc -p 4000 option to start a server on port 4000.
From here, you can open up
http://localhost:4000 in your browser and explore the documentation. The interface isn't pretty, but the job gets done.
Outputting PyDoc as HTML
Finally, we can output the documentation as HTML by passing the
-w option to
pydoc -w src.math outputs HTML into
src.math.html which contains the following:
Today’s post demonstrated how to use the
pydoc package to explore built-in and custom documentation.
Albeit a shallow exploration, the best way to improve on your searching capability is to use the command line in practice.
Resources and further reading
Originally posted on my blog. To see new posts without delay, read the posts there and subscribe to my newsletter.