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
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:
Now you can test and run the documentation locally using:
This allows you to review your changes in your local browser using
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
It then watches the
docs directory; when it spots changes, it will automatically rebuild
the documentation, and refresh the page in your browser.
The packages required by the documentation are managed by pip-tools, which
requirements.txt ensuring compatibility between packages.
The packages that the documentation requires are in
looks like a regular requirements file. Specific versions of packages can be
specified, or left without a version in which case the latest version which is
compatible with the other packages will be used.
furo Sphinx>4 sphinx-copybutton sphinxext-opengraph sphinxcontrib-spelling pyenchant>3
pip-compile the requirements are compiled into
Periodically requirements should be updated to ensure that new versions, most
importantly security patches, are used. This is done using the
cd docs pip-compile -U
requirements.txt pins specific versions and explains where
each required package comes from, for example:
datetime==4.3 # via -r requirements.in django==3.2.5 # via # django-classy-tags # django-cms # django-formtools # django-sekizai # django-treebeard django-classy-tags==2.0.0 # via # django-cms # django-sekizai django-cms==3.9.0 # via -r requirements.in django-formtools==2.3 # via django-cms
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.
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#
pyenchant are Python packages that will be installed in the
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
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
docs directory to conduct the checks.
This script expects to find a virtualenv at
docs/env, as installed by
make install (see
If no spelling errors have been detected,
make spelling will report:
build finished with problems. make: *** [spelling] Error 1
It will list any errors in your shell. Misspelt words will be also be listed in
Words that are not in the built-in dictionary can be added to
you are certain that a word is incorrectly flagged as misspelt, add it to the
document, in alphabetical order. Please do not add new words unless you are sure they should be
If you find technical terms are being flagged, please check that you have capitalised them
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.
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
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.
Our documentation is divided into the following main sections:
Getting Started (
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): technical reference for APIs, key models and so on
Release notes & upgrade information (
Who is behind django CMS (
who): who is behind the django CMS project
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 """""""""""""""""""""""
- use backticks -
The ``cms.models.pagemodel`` contains several important methods.
Before you start, edit ``settings.py``.
names of fields and other specific items in the Admin interface:
Edit the ``Redirect`` field.
- use backticks -
- use emphasis -
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 emphasis -
- use strong emphasis -
buttons that perform an action:
Hit **View published** or **Save as draft**.
- use strong emphasis -
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: “
Placeholdermethods can be overwritten as required” - when appropriate, link the term to further reference documentation as well as simply highlighting it.
internal cross-references liberally.
Use absolute links to other documentation pages -
rather than relative links -
:doc:`/../toolbar`. This makes it easier to
run search-and-replaces when items are moved in the structure.