Documenting a python script and REST API with 'PyDoc' and 'Swagger OpenAPI Specification' respectively

Documenting a python app appropriately goes along way in communicating what the app does and what is expected of it.

In this post, I will introduce you to two tools you can easily use to create and keep appropriate documentation of your python app.

The first is the PyDoc module which is a standard documentation module in python programming language similar to PerlDoc and JavaDoc for Perl and Java programming languages respectively. With PyDoc, we can generate text and HTML pages with documentation specifics.

The second tool is the Swagger (aka OpenAPI ) which is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services.

PyDoc: Documenting a python script

Pydoc is a Python documentation tool. On cmd enter this: python -m pydoc
You will see that all that the pydoc module is capable of doing as explained below....

1) pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

As an example enter: python -m pydoc pandas to see the documentation on the pandas module (note you should have already install "pandas" for you to see its documentation).

2) pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

An example to search for the keyword 'sql' is: python -m pydoc -k sql
All the keywords related to 'sql' on your python environment will be returned as seen below.

3) pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

For example, python -m pydoc -p 0 started an arbitrary unused port '61281' http://localhost:61281 in my case. Yours will definitely be on a different port.

On the cmd use letter 'b' to browse and 'q' to quit/stop the HTTP server.

4) pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  The -p option can be used with
    the -b option to explicitly specify the server port.

Example is: python -m pydoc -b will start the server doc automatically, it is just a handy shortcut for the above.


5) pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

This enable you generate a HTML doc for a module or a script you have written. Example is: python -m pydoc -w XXX where XXX can be a module or a script file name.

This is useful if you want to share or host the doc, you simply share the resulting html file with others. Below is a written sample script I did like to document. Save it as 'testScript.py' and run the command from the folder that contains the script: python -m pydoc -w testScript

This will generate a html doc for the script that you can share with other developers as seen below. The script contains classes, methods and function with multi line comments (doc strings) in them, the html doc is generated based on those multi line comments (doc strings).

'''
Author: Umar Yusuf
Date: 2019/04/01
This python script, demonstrates how a module is documented for easy future reference.
Hope you like it!
'''

class ClassA(object):
    """Here is the docstring for ClassA"""
    def __init__(self, arg):
        super(ClassA, self).__init__()
        self.arg = arg

    def myMethod(self):
        '''A function in a class is a know as a METHOD'''
        pass
        


class ClassB(ClassA):
    """Here is the docstring for second ClassB. It inherits from ClassA"""
    def __init__(self, arg):
        super(ClassB, self).__init__()
        self.arg = arg
        

# --------------------
# These are functions since they are outside the class definition
# Python program to multiply two numbers

def multiply(a, b):
    '''
    This function takes two numbers in the form of input and multiplies them.
    It displays the multiplication as the result.
    '''
    print("Result= ", (a * b))


# functions calling
multiply(5, 2)

Recap
a) Show module's doc: python -m pydoc XXX 
b) Search for keyword: python -m pydoc -k XXX
c) Start python doc on http port: python -m pydoc -p 0
d) Shortcut for http server doc: python -m pydoc -b
e) Generates HTML file for modules or written scripts: python -m pydoc -w XXX

Swagger: Documenting a python REST API


coming soon...