This section of Plone content management system Developer Documentation is no longer under active maintance. The section is included as the reference for older technologies (Plone 2.x, Plone 3.x). Some of the practices described in this documents may still work, but are not recommended to be used in your active Plone development. Use at your own risk.
If you arrived at this page by a web search we recommend to also see the Plone Developer Documentation front page .
How to write and submit content for the Plone Developer Documentation.
This chapter explains the basics of editing, updating and contributing to the Plone Developer Documentation.
Plone community runs a documentation team which is responsible for keeping Plone documentation coherent. To reach this team for any questions please contact
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.
This is the recommended method of editing the documentation for advanced users. 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.
git clone https://github.com/collective/collective.developermanual
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.7 bootstrap.py
git commit -m "My message about my changes" git push
Here are some Sphinx coding conventions used in the documentation.
Each page must contain, in this order:
================================== Writing and updating this document ==================================
.. 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
Each section (folder) must contain
.. toctree:: :maxdepth: 2 chapter1 chapter2 chapter3
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 ````````` ...
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/
This *word* is italics.
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`
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:: :sorted:
* First bullet * Second bullet with `a link <http://opensourcehacker.com>`_
.. warning:: This is a warning box (red)
.. note:: This is a note box (yellow)
.. TODO:: This is a TODO item
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:
Once you write code documentation:
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. There is also a nice plugin with enhanced functionalities called Riv.
Use semantic linefeeds (http://rhodesmill.org/brandon/2012/one-sentence-per-line/) when you are editing restructured text (or any other interpreted rich text format) because it will greatly improve the editing and maintenance of your documents.
Take this example paragraph:
Patterns can take options in two ways: from the DOM or via the jQuery interface. It is highly recommended to use the DOM interface, since it offers a lot more flexibility compared to the jQuery approach. Also, if you wish to use the automatic binding and rebinding functionality, the DOM approach is more straightforward and hassle-free.
Notice how it's easier to just reshuffle sentences and add stuff if, instead of using your editor "autowrap" feature, you manually insert line breaks after full stops, commas, or upon "grammatical" boundaries (and not merely word ones).
The source code of this file is hosted on GitHub. Everyone can update and fix errors in this document with few clicks - no downloads needed.
For basic information about updating this manual and Sphinx format please see Writing and updating the manual guide.