Developer's corner
===============================================================================
This section describes a set of guidelines for the developers of the Enaml.
.. note:: The content of this section is currently under discussion and
the guidelines are only suggestions.
.. GitHub Branches
.. ---------------
.. The following table provides a summary of the main developing branches and
.. their purpose
.. ================== ============================================
.. Label Description
.. ================== ============================================
.. ``master`` main stable branch
.. ``develop`` developing branch (unstable)
.. ================== ============================================
Documentation
-------------------------------------------------------------------------------
Sphinx Configuration
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
A Sphinx extension ``enamldoc``, found in :py:mod:`enamldoc.sphinx_ext` lets
Sphinx recognize and document |Enaml| objects.
Sphinx Directives and Roles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. rst:directive:: enaml:enaml_decl
For |Enaml| declarations. It will format similarly to a function, but with
the base object in the place arguments.
.. enaml:enaml_decl:: Foo(Bar)
.. enaml:enaml_decl:: enaml.stdlib.fields.RandomField
.. rst:directive:: autoenaml_decl:: import.hierarchy.enaml_declaration
Automatically generate the object description from an |Enaml| file. Specify
the object to document as though you were importing it.
.. autoenaml_decl:: enaml.stdlib.fields.IntField
.. rst:directive:: enaml:enaml_defn
For |Enaml| **enamldef** statements. Arguments display as with functions.
.. rst:directive:: autoenaml_defn:: import.hierarchy.enaml_defn
Automatically generate the object description from an |Enaml| file. Specify
the object to describe as though you were importing it.
.. rst:directive:: automodule::
automodule works for |Enaml| files as it does for python modules. No
special syntax is necessary.
.. #rst:role:: enaml_comp
.. Use the :rst:role:`enaml_comp` role to create a cross-reference to a
.. previously described ``enaml_decl`` or ``enaml_defn``
Including the Sphinx extension ``refactor_doc`` allows use of formatted
docstrings as described below.
.. automodule:: enamldoc.sphinx_ext
:members:
.. inheritance-diagram::
enamldoc.sphinx_ext.EnamlComponentDocumenter
enamldoc.sphinx_ext.EnamlDocstringSignatureMixin
enamldoc.sphinx_ext.DeclarativeDocumenter
enamldoc.sphinx_ext.EnamlModuleDocumenter
Sphinx Source
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
For Sphinx source, please use 4 spaces for indention and a UTF-8 encoding.
The line length is preferred to be between 72-74 characters.
Due to the magic under the hood of the traits objects, automatically
extracting documentation from the source with the standard autodoc tools
is a little tricky. Enaml's Sphinx source should therefore use the following
conventions:
- When documenting classes with Traits the sphinx directive
``.. autoattribute::`` does not work. To document single attributes
use the (undocumented) ``.. autoattributeinstance::`` directive
instead.
- The ``..autoclass::`` directive works fine as long as specific
members are not specified in the ``:members:`` context parameter.
Source Code
-----------
The coding style follows the `PEP 8 `_
guidelines and uses 4 spaces for indention. The maximum line length is 80
characters; however, the documentation is preferred to be between 72-74
characters.
Preamble
++++++++
The preamble of each file contains copyright notice. The following example
can be used as a template
.. include:: preamble.py
:literal:
Docstrings
++++++++++
The current documentation uses the autodoc extension of the Sphinx
distribution. The autodoc parsing is also extended to convert heading-based
docstring descriptions to standard reStructedText role directives.
Traits classes
^^^^^^^^^^^^^^
In order to create autodoc-friendly docstrings for classes that inherit
from `traits.HasTraits`, please consider the following:
- Avoid placing headings (except those that are described below) in
the multi-line docstrings since they are not rendered properly by
Sphinx.
- Document the class attributes using one or multiple lines commented
with ``#:`` before (i.e. above) the attribute definition. These will
be picked up by the autodoc commands and used as the docstring for
the following value::
# this comment will not appear since it lacks the ':'
#: The file name of the .qbc file to load
filename = File
- Alternative you can document the attributes at the main class using
the Attribute heading. The current autodoc extension supports
the following headings for classes:
========== ==========================================================
Heading Description
========== ==========================================================
Methods Class methods
Attributes Set of attributes
Notes Useful notes (one paragraph)
See Also References
========== ==========================================================
For example, the Python code
.. include:: traits_class.py
:literal:
leads to this Sphinx output (using ``..autoclass::``):
.. currentmodule:: traits_class
.. autoclass:: Myclass
:members:
.. autoclass:: Otherclass
:members:
Functions
^^^^^^^^^
In order to create autodoc-friendly docstrings for functions, please consider
the following:
- The current parser extension supports the following headings for
functions:
========= ==========================================================
Heading Description
========= ==========================================================
Arguments Set of function arguments and their usage
Returns Return values of the function
Raises Errors and the cases in which they are raised
Yields Successive results of the generator
========= ==========================================================
- Each section/heading can accept items with one of the following
structures (spaces around ``:`` are important)::
---------
:
:
:
---------
The last form is useful when a paragraph is more appropriate than a
an item list.
- Empty headings are removed and do not appear in the sphinx
documentation
.. note:: The use of the headings is optional. The developer can use
directly the rst role directives to format the docstrings. However,
using the headings, the dosctring is also readable in interactive
python sessions.
Example
~~~~~~~
::
"""Extract the fields from the docstring
Parse the fields into tuples of name, type and description in a
list of strings. The strings are also removed from the list.
Arguments
---------
indent : str, optional
the indent argument is used to make sure that only the lines
with the same indent are considered when checking for a
field header line. The value is used to define the field
checking function.
field_check : function
Optional function to use for checking if the next line is a
field. The signature of the function is ``foo(line)`` and it
should return ``True`` if the line contains a valid field
The default function is checking for fields of the following
formats::
:
or::
:
Where the name has to be one word.
Returns
-------
parameters : list of tuples
list of parsed parameter tuples as returned from the
:meth:`~BaseDocstring.parse_field` method.
"""
.. currentmodule:: refactordoc
.. automethod:: FunctionDoc.extract_fields