General Writing Guidelines


  • All pages should be in ReStructured Text, and have a .rst extension.

  • Images should be in .png, or .jpg format.

  • Please, don’t use .gif, because the PDF-generating software has issues with that.

Document Page Format

Here are some Sphinx coding conventions used in the documentation.

Table Of Contents

Make sure all .rst files are referenced with a Table of Contents directive, like this example:

.. toctree::
   :maxdepth: 2



The files themselves will have an extension of .rst, but you don’t specify that extension in the toctree directive.

Page Structure

Each page should contain, in this order:

  • The main heading. This will be visible in the table of contents:

Writing And Updating This Document
  • A single paragraph of text consisting of 1-3 sentences is recommended, so that the same text fits into the search engine results:

.. topic:: Description

   This text will go to Plone's pages description field.

A number of paragraphs: The actual content of the document page:


Below is the list of documentation and references.

Section Structure

Each section (folder) must contain

  • index.rst with:

  • Section heading: This will be visible in the table of contents

  • A single paragraph summarizing what this section is all about. This will be mapped to Plone folder description.

  • Sphinx toctree directive, maxdepth 2. Each .rst file in the folder should be linked to this toctree.

.. toctree::
   :maxdepth: 2



Readers use the table of contents or scan through the headings to find the required content. Therefore, headings must reflect the information that the readers search.

For having consistent heading styles in all files it is recommended to follow strictly the rules stated in the Sphinx manual.

As individual files do not have so called “parts” or “chapters”, the headings would be underlined like this:






Syntax Highlighting

Sphinx does syntax highlighting using the Pygments library.

You can specify the language used for syntax highlighting by using the code-block directive:


.. code-block:: python

    if "foo" == "bar":
        # This is Python code

Interactive Python

.. code-block:: pycon

   >>> class Foo:
   ...     bar = 100
   >>> f = Foo()
   >>> / 0
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ZeroDivisionError: integer division or modulo by zero


.. code-block:: xml

    <somesnippet>Some XML</somesnippet>

UNIX Shell

.. code-block:: shell

   bin/plonectl fg

INI Files

.. code-block:: ini

   # A random part in the buildout
   recipe =
   option = value


.. code-block:: javascript

   var $el = $('<div/>');
   var value = '<script>alert("hi")</script>';

If syntax highlighting is not enabled for your code block, you probably have a syntax error and Pygments will fail silently.


reST supports an image directive:

.. image:: ../_static/plone_donut.png
   :alt: Picture of Plone Donut

When used within Sphinx, the file name given (here plone_donut.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory.

For example, the file sketch/spam.rst could refer to the image _static/plone_donut.png as ../_static/plone_donut.png or /_static/plone_donut.png.

Other Sphinx And ReStructured Text Source Snippets


This *word* is italics.


This **word** is in bold text.

Labels for graphical user interfaces (GUI), including buttons, menu items, form controls, and links.

Click the :guilabel:`Submit` button.

The above reStructuredText renders as follows.

Click the Submit button.

Inline code highlighting:

This is :func:`aFunction`, this is the :mod:`some.module` that contains the :class:`some.module.MyClass`


These Python objects are rendered as hyperlinks if the symbol is mentioned in a relevant directive.

See and

Making an external link (note the underscore at the end):

`This is an external link to <>`_

Making an internal link:

:doc:`This is a link to </introduction/writing.txt>`
See also :ref:`somewhere` (assuming that a line containing only
``.. _somewhere:`` exists above a heading in any file of this
documentation) ...
And a link to the term :term:`foo` assuming that ``foo`` is defined in the glossary.


.. glossary:: :sorted:

Bullet list:

* First bullet
* Second bullet with `a link <>`_


.. warning::

   This is a warning box (yellow)


This is a warning box (yellow)

.. error::

   This is an error box (red)


This is an error box (red)


.. note::

   This is a note box (blue)


This is a note box (blue)

.. TODO::

   This is a TODO item


This is a TODO item

You can find a brief introduction to reStructuredText (reST) on

Including Gists

Sometimes it is handy to include gists. This can be useful if you want to include for example a configuration file.

For including gists just use the gist directive

.. gist::


Since this documentation serves as source for various versions (html, PDF, others), please always include a link to the gist under the gist directive.