Phoenix Docstrings Guidelines¶This document 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 at least two places:
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.
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:
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:
.. method:: 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`: integer
:returns: ``True`` if the value was successfully set, ``False`` otherwise.
:rtype: bool
:raise: `Exception` when the item is not a 3-state checkbox item.
This will render like this:
- Set3StateValue(self, state):
Sets the checkbox item to the given state.
Parameters: state (integer) – can be one of: wx.CHK_UNCHECKED (check is off), wx.CHK_CHECKED (check is on) or wx.CHK_UNDETERMINED (check is mixed). Returns: True if the value was successfully set, False otherwise. Return type: bool Raise : Exception when the item is not a 3-state checkbox item.
It is also possible to combine parameter type and description, if the type is a single word, like this:
:param integer `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is off), ``wx.CHK_CHECKED``
(check is on) or ``wx.CHK_UNDETERMINED`` (check is mixed).
In general, the standards for the :param field are the following:
Do not use the @param construct, as I am not sure Sphinx and docutils understand it;
Always try and define the parameter type: if the parameter is another Phoenix class, you can simply write this:
:param Point `pt`: the mouse pointer location.
Or, alternatively:
:param `pt`: the mouse pointer location.
:type `pt`: Point
Similarly, for the :return: and :rtype: field, you may consider doing the following:
See also
Admonitions are specially marked “topics” that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. For example:
.. warning:: I am a warning.
Will render as:
Warning
I am a warning.
Currently, the sphinx_generator tool recognizes the following admonitions:
You can put pretty much anything inside an admonition section, as long as it is properly indented. The recommendation is to implement it like this:
.. note::
The class :ref:`TreeCtrl` can be used to display a tree, with these notes:
- The note contains all indented body elements
following.
- It includes this bullet list.
Which will render as follows:
Note
The class TreeCtrl can be used to display a tree, with these notes:
In addition to the aforementioned admonitions, you can also use the default Sphinx directives like .. versionadded:: and .. versionchanged::, to highlight the fact that some method, function or class has been added/modified starting with a particular Phoenix version.
See also
If you wish to contribute a (short) sample to be included in the documentation, please follow these conventions:
Name the snippet of code like classname.methodname.INTEGER.py, i.e. if you wish to contribute 2 snippets about the CheckBox.SetValue method, please name your snippet files like this:
At the very top of the snippet file (on the first line), put your name, or your alias, or anything you use as internet name preceeded by a double-hash, i.e.:
##Andrea Gavana
So that your source code looks more or less like this:
##Chris Barker
#!/usr/bin/env python
"""
A simple test of the GridBagSizer
http://wiki.wxpython.org/index.cgi/WriteItYourself
"""
# Whatever code here...
def SendSizeEvent(self):
self.AdjustMySize()
This snippet will end up in the snippets contrib folder, to differentiate it from the snippets automatically generated when parsing the wxWidgets C++ XML documentation.
Please keep the snippets as short as possible: they don’t need to be fully-runnable and self contained applications, they are simply meant to show a particular/clever/unusual way of using a method, a class or a function.
Please do send your sample snippets to me at this e-mail address or, if you have commit rights in the current Phoenix SVN area, feel free to upload them yourself under the following folder:
/trunk/docs/sphinx/rest_substitutions/snippets/python/contrib
Currently Phoenix is relatively short of widgets screenshots, especially on Linux/Mac platforms.
If you wish to contribute a screenshot of a widget to be included in the documentation, please follow these conventions:
Please do send your screenshots to me at this e-mail address or, if you have commit rights in the current Phoenix SVN area, feel free to upload them yourself under the following folder:
/trunk/docs/sphinx/_static/images/widgets/fullsize
Please make sure to upload your images in the appropriate sub-folder, depending on the platform you chose to take the screenshots on.