General Writing Guidelines

Overview

  • 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

   quickstart
   working_examples
   absolutely_all_options_explained
   how_to_contribute

Note

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:

Introduction
============

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

   chapter1
   chapter2
   chapter3

Headings

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:

===
One
===

Two
===

Three
-----

Four
~~~~

Five
^^^^

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:

Python

.. code-block:: python

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

Interactive Python

.. code-block:: pycon

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

XML

.. code-block:: xml

    <somesnippet>Some XML</somesnippet>

UNIX Shell

.. code-block:: shell

   bin/plonectl fg

INI Files

.. code-block:: ini

   [some-part]
   # A random part in the buildout
   recipe = collective.recipe.foo
   option = value

JavaScript

.. code-block:: javascript

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

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

Images

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

Italics:

This *word* is italics.

Strong:

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`

Note

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

See http://sphinx-doc.org/domains.html and http://sphinx-doc.org/ext/autodoc.html

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

`This is an external link to <http://opensourcehacker.com>`_

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:

.. glossary:: :sorted:

Bullet list:

* First bullet
* Second bullet with `a link <http://opensourcehacker.com>`_

Warning:

.. warning::

   This is a warning box (yellow)

Warning

This is a warning box (yellow)

.. error::

   This is an error box (red)

Error

This is an error box (red)

Note:

.. note::

   This is a note box (blue)

Note

This is a note box (blue)

.. TODO::

   This is a TODO item

Todo

This is a TODO item

You can find a brief introduction to reStructuredText (reST) on http://www.sphinx-doc.org/en/stable/rest.html

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:: https://gist.github.com/shomah4a/5149412

Note

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