writing documentation is the dream of
every engineer
it gives you a chance to describe your
code in beautiful prose and the
documentation often takes up more space
than the code itself
what could be more fun than that luckily
python gives you a tool to share your
written masterpiece with your fellow
engineers
the pi doc module
this will generate web pages from your
python documentation
it can even launch a web server so your
colleagues can read about how to use
your code before they give up and ask
you in person
i hope you brought your dancing shoes
because this documentation party is
about to begin
prepare to have your mind blown because
we are going to start by looking at the
documentation for the documentation tool
the fastest way to do this is to simply
run the pi doc module
do not forget to use the dash m option
to run the pi doc module as a script
the first way we will use pi doc is to
look at the documentation for a class
module or function
for example
we can use pi doc to look at the
documentation for the math module
in addition to a brief description of
the module it describes each function it
contains
we can also look at the help text for a
class such as tuple
or even a function like pow
you can also access this in interactive
mode by using the help function
but one small benefit with pi doc is
that you do not have to import a module
to look at its help text
otherwise this is identical to starting
python and calling the help function
but wait there is more
the second use of the pi doc module is
to search all modules for a certain
keyword
excitement level plus plus
for example let us search the python
modules for the keyword
ftp my system has two results a class
and its test class
you may get something else if you are
using a different version of python or
have additional python libraries
installed
let us use pydoc to learn more about the
ftp lib class
what is this
an example
be still my beating heart this is some
grade a help text
let us do another search
does python contain any modules with the
keyword sql
i would say this is a resounding yes
let us dive into the sql lite3 package
if we page down we see this package
comes with a variety of errors classes
and functions
we will learn how to use these in a
separate video
let us return to the list of pi doc
features
the third entry says you can use pi doc
to start an http server on a specified
port for browsing the documentation
we will start a server on port 314
this will give us a pi doc server on
port pi
see what i did there
python gives us the url for browsing all
the documentation
you can open a browser and type in this
url yourself or you can simply enter b
python will then open a browser and go
to the documentation home page for you
the top section displays the built-in
modules
clicking one will give you full details
for example if you click on the c math
link you can learn about this module
it is called c math for complex math
because these functions work with
complex numbers
you return to the homepage by clicking
on the module index link above if you
scroll further down you can see there is
a tremendous number of modules and
packages in the python library
i would strongly recommend you take the
time to browse these modules to become
familiar with what features are
available to you for example clicking on
the xml package gives you an idea of
what xml capabilities come standard with
python
if you want to view the documentation
for a specific item then enter it in the
text box above
and click get
python will then fetch the documentation
for that function class module or
package
if you are not exactly sure of the name
of the item you can search for it as
well
for example
search for the term rpc
which is short for remote procedure call
the search results are listed below
clicking on a result takes you to the
documentation
as you can see this is a fast way to
browse find and search through the
python documentation
to stop the documentation server return
to the console and enter queue
return once more to the pi doc
documentation
there are two features remaining
calling doc with the dash b option will
start the server on an available port
and launch a browser for you
a handy shortcut indeed especially if
you have other services running on a
large number of ports
this brings us to the final feature the
ability to generate html files of the
documentation
as a demonstration we will create a
folder called pi doc demo
once inside we will generate an html
file with a documentation for the json
package
to do this run pidoc with a dash w
option and then enter the name of the
function class module or package
you can see that the file json.html
was created
if you open this in a browser you can
see the documentation
this feature is especially useful if you
want to host the python documentation
for your code on a separate server
rather than your workstation
all too often engineers write beautiful
documentation only to find that others
refuse to read the manual
but with pi doc you can turn all your
python documentation into an interactive
website with pretty colors and clicky
links
this is a fantastic aid when writing
code and an invaluable tool when working
on large projects
now run
run to the nearest workstation and get
to work using pi doc
please hurry there is not enough time to
subscribe to our channel documentation
comes first
it comes first
after subscribing
do