Writing and updating the documentation

Description

How to write and submit content for the Plone Developer Documentation.

Introduction

This chapter explains the basics of editing, updating and contributing to the Plone Developer Documentation.

Contributions needed

Below is the list of documentation and references we'd like to see:

• New code snippets and system descriptions
• Links to external documentation
• Links to component READMEs
• Links to blog posts talking about particular issues
• Links to email list discussions
• Links to source code (directly to the version control)
• Clean up and restructuring (see the todo list)

Committing changes to the documentation Github

• You can commit file edits through GitHub web interface using the Fork and Edit button, followed by a pull request.
• Alternatively, clone the repository using git, perform changes, and push them to your fork. Then submit a pull request.

The Plone collective GitHub repository has open-for-all contribution access. If you want to contribute changes without asking the maintainers to merge them, please add your GitHub username to your profile on plone.org and request access here.

Using git

This is the recommended method. Please do not be afraid to commit. If you break the documentation or add invalid information, it will be cleaned up sooner or later and no one is going to blame you: human errors happen all the time.

• Learn about Sphinx and restructured text.
• Get the documentation source files:

git clone https://github.com/collective/collective.developermanual

• Bootstrap with Python 2.5 or later. We use a version of Sphinx that has dropped Python 2.4 support.

Note

You do not need to bootstrap and buildout if you simply want to make a quick edit the documentation. Go to the "source" directory to find the files. Continue reading if you want to run a complete local copy.

cd collective.developermanual
python2.6 bootstrap.py

• Run buildout (or just bin/develop update) to get the latest documentation and code.
• Edit the file(s) which you want to update.
• Check that building with Sphinx does not give warnings:

bin/sphinx-build source build

• Commit changes:

git commit -m "My message about my changes"
git push

Document page format

Here are some Sphinx coding conventions used in the documentation.

Page structure

Each page must contain, in this order:

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

==================================
Writing and updating this document
==================================

• The description of the page, which will appear in Plone's Description Dublin Core metadata field. This created using the reST admonition directive. A single paragraph of text consisting of 1-3 sentences is recommended, so that the same text fits into the search engine results (Google):

.. admonition:: Description

   This text will go to Plone's pages description field. It will appear in
   the search engine listings for the page.

The contents directive will cause Sphinx to generate the Table of Contents shortcut links at the start of the page. Using the local option excludes the page itself and ToC title from the listing:

.. contents:: :local:

Introduction paragraph: A brief overview:

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

This chapter will describe the basics of how to contribute to this document.

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

Contributions needed
====================

Below is the list of documentation and references we'd like to see

Section structure

Each section (folder) must contain

• index.txt 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 .txt file in the folder should be linked to this toctree.

.. toctree::
   :maxdepth: 2

   chapter1
   chapter2
   chapter3

Headings style guide

ReStructured text and Sphinx enable any style you would prefer for the various heading level you would need. In example, underlining level 1 headings with ., level 2 headings with # and level 3 headings with | is perfect as far as docutils is concerned. But not for a human documentation maintainer.

In order to have consistent heading styles in all files that make this great document, it is recommended to follow strictly the rules stated in the Sphinx manual here: http://sphinx.pocoo.org/rest.html#sections

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

Heading 1
=========
...
Heading 2
---------
...
Heading 3
^^^^^^^^^
...
Heading 4
`````````
...

Syntax highlighting

Sphinx does syntax highlighting using the Pygments library.

You can specify different highlighting for a code block using the following syntax:

With two colons you start a code block using the default highlighter::

    # Some Python code here
    # The language defaults to Python, we don't need to set it
    if 1 == 2:
        pass

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
        pass

For example, to specify XML:

.. code-block:: xml

    <somesnippet>Some XML</somesnippet>

... or UNIX shell:

.. code-block:: console

   # A comment
   sh myscript.sh

... or a buildout.cfg:

.. code-block:: ini

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

... or 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

Setting the highlighting mode for the whole document:

.. highlight:: console

All code blocks in this doc use console highlighting by default::

   some shell commands

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

The full list of lexers and associated short names is here: http://pygments.org/docs/lexers/

Other Sphinx and restructured text source snippets

Italics:

This *word* is italics.

Strong:

This **word** is in bold text.

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.pocoo.org/domains.html and http://sphinx.pocoo.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.

Bullet list:

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

Warning:

.. warning::

   This is a warning box (red)

Note:

.. note::

   This is a note box (yellow)

TODO item (see TODO list:

.. TODO::

   This is a TODO item

Code documentation

For certain kinds of documentation it is better to write the documentation in parts of the Plone core code base. This can be done using the autodoc sphinx extension.

... to include a module docstring:

.. automodule:: plone.app.contentrules.exportimport

... to include a class docstring:

.. autoclass:: Products.CMFEditions.exportimport.repository.RepositoryToolXMLAdapter

... or to include both a module and class docstrings:

.. automodule:: Products.CMFEditions.exportimport.repository
   :members: RepositoryToolXMLAdapter

Not all documentation is best kept with the code. You should use autodoc if:

• the documentation is reasonably self-contained and relates just to that module;
• it's mainly reference material, rather than tutorial-style documentation;
• you think it's more likely to be maintained by the code authors.

Once you write code documentation:

1. find an appropriate place in this manual to place it. Make sure it flows and makes when sense read with the documentation around it;
2. include a comment in the docstring mentioning its use in this manual so those editing the code can test the manual if changes are made;
3. add the module to the autocheckout value in the manual's buildout.cfg.

Some helper tools

Emacs has a nice rst-mode. This mode comes with some Emacs distros. Try M-x rst-mode in your Emacs and enjoy syntax coloration, underlining a heading with ^C ^A

Eclipse users can install ReST Editor through the Eclipse Marketplace.

Vim does syntax highlighting for RST files.