Contributing documentation

Perhaps considered “boring” by hard-core coders, documentation is sometimes even more important than code! This is what brings fresh blood to a project, and serves as a reference for old timers. On top of this, documentation is the one area where less technical people can help most - you just need to write simple, unfussy English. Elegance of style is a secondary consideration, and your prose can be improved later if necessary.

Contributions to the documentation earn the greatest respect from the core developers and the django CMS community.

Documentation should be:

• written using valid Sphinx/restructuredText syntax (see below for specifics); the file extension should be .rst

• wrapped at 100 characters per line

• written in English, using British English spelling and punctuation

• accessible - you should assume the reader to be moderately familiar with Python and Django, but not anything else. Link to documentation of libraries you use, for example, even if they are “obvious” to you

Merging documentation is pretty fast and painless.

Except for the tiniest of change, we recommend that you test them before submitting.

Building the documentation

Follow the same steps above to fork and clone the project locally. Next, cd into the django-cms/docs and install the requirements:

make install

Now you can test and run the documentation locally using:

make run

This allows you to review your changes in your local browser using http://localhost:8001/.

Note

What this does

make install is roughly the equivalent of:

virtualenv env
source env/bin/activate
pip install -r requirements.txt
cd docs
make html

make run runs make html, and serves the built documentation on port 8001 (that is, at http://localhost:8001/.

It then watches the docs directory; when it spots changes, it will automatically rebuild the documentation, and refresh the page in your browser.

Spelling

We use sphinxcontrib-spelling, which in turn uses pyenchant and enchant to check the spelling of the documentation.

You need to check your spelling before submitting documentation.

Important

We use British English rather than US English spellings. This means that we use colour rather than color, emphasise rather than emphasize and so on.

Install the spelling software

sphinxcontrib-spelling and pyenchant are Python packages that will be installed in the virtualenv docs/env when you run make install (see above).

You will need to have enchant installed too, if it is not already. The easy way to check is to run make spelling from the docs directory. If it runs successfully, you don’t need to do anything, but if not you will have to install enchant for your system. For example, on OS X:

brew install enchant

or Debian Linux:

apt-get install enchant

Check spelling

Run:

make spelling

in the docs directory to conduct the checks.

Note

This script expects to find a virtualenv at docs/env, as installed by make install (see above).

If no spelling errors have been detected, make spelling will report:

build succeeded.

Otherwise:

build finished with problems.
make: *** [spelling] Error 1

It will list any errors in your shell. Misspelt words will be also be listed in build/spelling/output.txt

Words that are not in the built-in dictionary can be added to docs/spelling_wordlist. If you are certain that a word is incorrectly flagged as misspelt, add it to the spelling_wordlist document, in alphabetical order. Please do not add new words unless you are sure they should be in there.

If you find technical terms are being flagged, please check that you have capitalised them correctly - javascript and css are incorrect spellings for example. Commands and special names (of classes, modules, etc) in double backticks - `` - will mean that they are not caught by the spelling checker.

Important

You may well find that some words that pass the spelling test on one system but not on another. Dictionaries on different systems contain different words and even behave differently. The important thing is that the spelling tests pass on Travis when you submit a pull request.

Making a pull request

Before you commit any changes, you need to check spellings with make spelling and rebuild the docs using make html. If everything looks good, then it’s time to push your changes to GitHub and open a pull request in the usual way.

Documentation structure

Our documentation is divided into the following main sections:

• Tutorials (introduction): step-by-step, beginning-to-end tutorials to get you up and running

• How-to guides (how_to): step-by-step guides covering more advanced development

• Key topics (topics): explanations of key parts of the system

• Reference (reference): technical reference for APIs, key models and so on

• Development & community (contributing)

• Release notes & upgrade information (upgrade)

• Using django CMS (user): guides for using rather than setting up or developing for the CMS

Documentation markup

Sections

We mostly follow the Python documentation conventions for section marking:

##########
Page title
##########
*******
heading
*******
sub-heading
===========
sub-sub-heading
---------------
sub-sub-sub-heading
^^^^^^^^^^^^^^^^^^^
sub-sub-sub-sub-heading
"""""""""""""""""""""""

Inline markup

• use backticks - `` - for:

  • literals:

    The ``cms.models.pagemodel`` contains several important methods.

  • filenames:

    Before you start, edit ``settings.py``.

  • names of fields and other specific items in the Admin interface:

    Edit the ``Redirect`` field.

• use emphasis - *Home* - around:

  • the names of available options in or parts of the Admin:

    To hide and show the *Toolbar*, use the...

  • the names of important modes or states:

    ... in order to switch to *Edit mode*.

  • values in or of fields:

    Enter *Home* in the field.

• use strong emphasis - ** - around:

  • buttons that perform an action:

    Hit **View published** or **Save as draft**.

Rules for using technical words

There should be one consistent way of rendering any technical word, depending on its context. Please follow these rules:

• in general use, simply use the word as if it were any ordinary word, with no capitalisation or highlighting: “Your placeholder can now be used.”

• at the start of sentences or titles, capitalise in the usual way: “Placeholder management guide”

• when introducing the term for the the first time, or for the first time in a document, you may highlight it to draw attention to it: “Placeholders are special model fields”.

• when the word refers specifically to an object in the code, highlight it as a literal: “Placeholder methods can be overwritten as required” - when appropriate, link the term to further reference documentation as well as simply highlighting it.

References

Create:

.. _testing:

and use:

:ref:`testing`

internal cross-references liberally.

Use absolute links to other documentation pages - :doc:`/how_to/toolbar` - rather than relative links - :doc:`/../toolbar` . This makes it easier to run search-and-replaces when items are moved in the structure.