ProjectPhoenix/DocumentationProject

Project Phoenix Documentation

This page gives a brief introduction about the current docstrings standards in the Phoenix project. Most of the documentation in the Phoenix core is automatically generated by parsing the wxWidgets XML docs; however, Phoenix has its own pure-Python functions and classes in the wx.lib package.

This requires manual editing of the source Python files, to adapt the existing docstrings to the Phoenix standard. As per BDFL statement:

https://groups.google.com/forum/?fromgroups#!topic/wxPython-dev/NyXm58sUNrs

A module in wx.lib will not be considered ready (and thus not included in the Phoenix distribution) if it doesn't have proper documentation and unittest.

This document is a starting point in setting some reasonable standards on how the pure-Python docstrings may be edited and improved to make the overall appearance of the Phoenix documentation consistent and pleasant.

Sphinx

Phoenix will use sphinx to generate the API documentation, which means that the Python docstrings format needs to comply with the RestructuredText directive.

Some very good RestructuredText (ReST) documentation resources are here:

There are a few important point when considering the quality of Python docstrings:

Module docstrings should always be at the top of the script, before any import statement;
As a convention (but it is not a strict rule), function/method docstrings should give a one-line summary of what that function/method does, and a more extended explanation separated from the summary line by a blank line. Then the various parameter definitions, return values and other remarks can be defined;
Class docstrings follow point (2), obviously excluding the parameter definitions and return values.

I will base my description of the docstrings format on the AGW library docstrings (distributed with wxPython as sub-package), as I like the format and I spent quite some time in improving them.

Module Docstrings

As for classes and methods, a brief summary of the module capabilities should be followed by a separated paragraph giving a more detailed explanation. Next, a simple, short usage sample should be given (in ReST format).

If the module contains an implementation of a widget/control, you may want to include a section briefly describing any particular window style (in terms of wxPython window style bits) this widget uses and another brief section mentioning any custom event this control may emit.

You can see an example of the module documentation strings here:

http://xoomer.virgilio.it/infinity77/Phoenix/_sources/lib.agw.aquabutton.txt

And the results when rendered to HTML by Sphinx:

http://xoomer.virgilio.it/infinity77/Phoenix/lib.agw.aquabutton.html

Class Docstrings

As I wrote above, class docstrings should include a brief, one-line summary of the class purpose and (optionally) a separated paragraph with a more in-depth explanation. The various scripts used to generate the Sphinx documentation from the Phoenix source code will take care to generate the inheritance diagram for the class, to highlight any sub/super class of this class and to create a summary list of methods/properties available in the class.

An example of class docstrings can be found here is as follows:

class CustomTreeCtrl(wx.ScrolledWindow):
    """
    :class:`CustomTreeCtrl` is a class that mimics the behaviour of :class:`TreeCtrl`, with almost the
    same base functionalities plus some more enhancements. This class does not rely on
    the native control, as it is a full owner-drawn tree control.
    """

Which will be rendered as follow in the HTML output:

http://xoomer.virgilio.it/infinity77/Phoenix/lib.agw.customtreectrl.CustomTreeCtrl.html

Function/Method Docstrings

Function and method docstrings can be customized a lot more, although they should include at minimum the method docstrings and the input parameters (arguments and keywords) description.

Function and method docstrings use the so-called Info Field List:

http://sphinx.pocoo.org/domains.html#info-field-lists

Info Field Lists refer to the various options available while documenting a method or a function, and in particular its parameters, keywords, return type and possibly raised Python Exceptions.

Inside Python object description directives, reST field lists with these fields are recognized and formatted nicely:

param, parameter, arg, argument, key, keyword: Description of a parameter.
type: Type of a parameter.
raises, raise, except, exception: That (and when) a specific exception is raised.
var, ivar, cvar: Description of a variable.
returns, return: Description of the return value.
rtype: Return type.

The field names must consist of one of these keywords and an argument (except for returns and rtype, which do not need an argument). This is best explained by an example:

    def Set3StateValue(self, state):
        """
        Sets the checkbox item to the given `state`.

        :param `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is off), ``wx.CHK_CHECKED``
         (check is on) or ``wx.CHK_UNDETERMINED`` (check is mixed).
        :type `state`: int

        :raise: `Exception` when the item is not a 3-state checkbox item.

        :note: This method raises an exception when the checkbox item is a 2-state checkbox
         and setting the state to ``wx.CHK_UNDETERMINED``.

        :note: This method is meaningful only for checkbox-like items.
        """

Which will render as follows in the generated HTML docs:

http://xoomer.virgilio.it/infinity77/Phoenix/lib.agw.customtreectrl.GenericTreeItem.html#lib.agw.customtreectrl.GenericTreeItem.Set3StateValue

Other Resources

Please refer to the official Phoenix documentation page:

http://wxpython.org/Phoenix/docs/html/DocstringsGuidelines.html

Which contains directions on how to include snippets of code in your docstrings and contributing widgets' screenshots.