Documenting

In general, follow the suggestions here.

Tones of Voice

The documentation needs to speak to three different groups of people, each with different needs.

  1. Designers writing scripts that use fontParts. This is the Public API.
  2. Developers implementing fontParts inside their own application. This is the Implementation API.
  3. Developers working on fontParts itself. This is the Internal Stuff.

Each of these needs a different tone of voice, level of detail and so on.

Public API

Most people reading the Public API will be looking for specific information about a specific method, property, etc. The text needs to be brief, easy to understand and quick to get the gist of.

  • write as if talking
  • don’t assume that the reader has more than basic Python proficiency
  • be detailed, but not overwhelming
  • keep technical jargon to a minimum
  • show examples

Examples

Examples should be simple and concise. They should show what is being documented and nothing else. The point of the documentation examples is to show how to use the method/function being explained, not to make a fully functional script. (Fully functional demo scripts will be a separate type of documentation.)

  • use interactive prompt style with >>>
  • use Python 3 syntax
  • don’t show more functionality than is necessary for what the documentation is explaining
  • don’t show import statements unless necessary
  • don’t show constructors unless that is what is being demonstrated
  • multiple examples each showing one thing are better than one example showing multiple things

Do this:

>>> font.glyphOrder = ["A", "B", "C"]
>>> font.glyphOrder
["A", "B", "C"]

Don’t do this:

import random
from fontTools.world import *

font = CurrentFont()
print(font.glyphOrder)
font.glyphOrder = sorted(font.glyphOrder)
print(font.glyphOrder)
order = list(font.glyphOrder)
random.shuffle(order)
font.glyphOrder = order
print(font.glyphOrder)

Implementation API

Developers reading the Implementation API will be looking for detailed information about what they need to do. The text needs to make their work as easy as possible.

  • write concisely
  • assume that the reader has computer science proficiency
  • cover requirements thoroughly
  • explain what can be expected of incoming data
  • explain what is expected of outgoing data
  • don’t leave anything to assumption or interpretation
  • always use may/must/should terminology

Internal Stuff

The code within fontParts itself should be written such that what the code is doing is immediately apparent. Thus, it should require very limited documentation, if any at all.

  • assume that the reader knows how fontParts works
  • funny jokes are allowed, but only if they are funny

Documentation Strings

Most of the documentation will be contained with the source code itself. Here’s the structure of how it should be done:

class BaseThing(BaseOtherThing):

    """
    This is a very brief explanation of the object.
    A note about when to create this object may be added.
    This text will be prepended to the string in __init__
    in the compiled documentation.
    """

    def aMethod(arg, kwarg="blah"):
        """
        A very brief description calling out majorly significant ``args``.

            >>> blah.public()
            "output"

        The next level of documentation is presented in paragraph
        form. This will detail what ``arg`` means/does, it's potential
        options (linking to :ref:`type-detail` or :class:`ObjectClass`
        as needed, the default value, any possible errors and so on.
        If a list is needed to detail what the method does, it should be
        presented as a list:

            * this happens
            * that happens
            * finally this happens

        It should read very simply and clearly. Next is a description
        of ``kwarg`` following the same form. If an argument has
        options they are to be presented as a table.

        +---------+-----------------------+
        | option1 | Sentence description. |
        +---------+-----------------------+
        | option2 | Sentence description. |
        +---------+-----------------------+

        Further explanations carry on for additional arguments
        and so on.

        .. note::

           If there is a special note, put it in a note section.
        """

    def _aMethod(arg, kwarg="blah"):
        """
        This is the environment implementation of :meth:`BaseThing.aMethod`.
        ``arg`` will be a :ref:`type-detail` that has been normalized with
        :func:`normalizers.normalizeValue`. If there are any notes
        on how to interpret this, it goes here. ``kwarg`` is now explained.
        The options for kwarg are detailed in :meth:`BaseThing.aMethod` rather
        than duplicated here. If something goes wrong a :exc:`FontPartsError`
        (or other applicable) error must be raised. This method must return
        a result of :ref:`type-detail` and the returned value will be normalized
        with :func:`normalizers.normalizeValue`.

        Subclassing statement such as: Subclasses may override this method.
        """

    aProperty = dynamicProperty(
        "base_aProperty",
        """
        A very brief description with optional :ref:`type-detail`.

            >>> print(font.aProperty)
            "output"

        Additional info if needed.
        """
    )

Quick Reference

Basic Formatting

*emphasis (italics)*
**strong (bold)**
``code`` Always use this for things like args, kwargs, ``True``, ``False`` and ``None``.

`Some text <http://target>`_
:mod:`module`
:func:`module.functionName`
:class:`ClassName`
:meth:`ClassName.methodName`
:attr:`ClassName.attribute`
:exc:`ExceptionName`
:ref:`my-reference-label`

* unordered
* list

#. ordered
#. list

+---------+--------------+
| option1 | Description. |
+---------+--------------+
| option2 | Description. |
+---------+--------------+

Frequently Used Stuff

Statements

  • This attribute is read only.
  • Subclasses must override this method.
  • Subclasses may override this method.

Value Types

fontParts
  • :ref:`type-string`
  • :ref:`type-int-float`
  • :ref:`type-coordinate`
  • :ref:`type-angle`
  • :ref:`type-identifier`
  • :ref:`type-color`
  • :ref:`type-transformation`
  • :ref:`type-immutable-list`
general
  • :ref:`type-string`
  • :ref:`type-int`
  • :ref:`type-float`
  • :ref:`type-hex`
  • :ref:`type-bool`
  • :ref:`type-tuple`
  • :ref:`type-list`
  • :ref:`type-dict`
  • :ref:`type-set`

Heading Levels

#######
Level 1
#######

*******
Level 2
*******

Level 3
=======

Level 4
-------

Level 5
^^^^^^^

Level 6
"""""""

Special Sections

.. note::
.. warning::
.. versionadded::
.. versionchanged::
.. seealso::