PyDoc - Inline Documentation

Now that the project contains libraries, providing some high-level documentation will become increasingly important. Python contains an inline documentation tool called PyDoc allowing code and comments to exist side-by-side. The objective is to change the comment blocks (#) to Python DocStrings which can be parsed by PyDoc.

• DocStrings are Strings wrapped in double quotes



""This is a single line docString"" 



• Often docStrings are wrapped in triple quotes to allow the text to span more than one line in the file.



"""This is a single line docString"""
"""This is a multi
   line
   docString""" 



• Add comments to modules, classes, and functions.
• Add a comment for the module at the start of the file
• Add comments for each class after the class definition
• Add comments for each function after the function definition

..\\HelloWorldLib.py

"""Module Hello World"""
def helloWorld(Title, Body):
    """Create a non-modal popup window
           Title  Title of the popup 
           Body   Body message of the popup"""
def helloWorld(Title, Body):
    popup( Body, Title) 

Extracting the library documentation requires another Sikuli project. It could be combined with the HelloWorld mainline, but it is not typical that library documentation would be created in the same project that uses the library (the documentation should pre-exist).

• Create a new Project ..\\..\\ParseInlineDocumentation.sikuli
• Add the base directory to the sys.path. Subdirectories are recursively added.
• import pydoc



import pydoc 



• Extract the DocStrings for HelloWorldLib.py



pydoc.writedoc("HelloWorldLib") 



• This creates the output documentation file "HelloWorldLib.html" in the Sikuli executable directory. Open
• Open the documentation. A command to do this automatically after generating the files is included in the parse script.

..\\ParseInlineDocumentation.sikuli\\ParseInlineDocumentation.py

myScriptPath = "...\\ library path \\"
if not myScriptPath in sys.path: sys.path.append(myScriptPath)
import pydoc


pydoc.writedoc("HelloWorldLib")
# Note that spaces in the URL must be denoted by their escape sequence
openApp("C:\\Program Files\\Mozilla Firefox\\firefox.exe file:///c:\Program%20Files\Sikuli%20X\HelloWorldLib.html")

The documentation will look like this: Hello World Inline Documentation

Further Reading:

• A case for inline documentation
• Python Inline Documentation
• Python pydoc manual
• Pydoc conventions

Special thanks to RaiMan for his assistance with getting this working. Sikuli Help Question re PyDoc

03-12-2012
Sikuli X-1.0rc3 (r905)