Contributing to the Documentation¶
XiVO documentation is generated with Sphinx. The source code is available on GitLab at https://gitlab.com/xivo.solutions/xivo-solutions-doc
Provided you already have Python installed on your system. You need first to install Sphinx : easy_install -U Sphinx
1.
Quick Reference
http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt
http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html
- 1
easy_install
can be found in the debian package python-setuptools :sudo apt-get install python-setuptools
Documentation guideline¶
Here’s the guideline/conventions to follow for the XiVO documentation.
Language¶
The documentation must be written in english, and only in english.
Sections¶
The top section of each file must be capitalized using the following rule: capitalization of all words, except for articles, prepositions, conjunctions, and forms of to be.
Correct:
The Vitamins are in My Fresh California Raisins
Incorrect:
The Vitamins Are In My Fresh California Raisins
Use the following punctuation characters:
*
with overline, for “file title”=
, for sections-
, for subsections^
, for subsubsections
Punctuation characters should be exactly as long as the section text.
Correct:
Section1
========
Incorrect:
Section2
==========
There should be 2 empty lines between sections, except when an empty section is followed by another section.
Correct:
Section1
========
Foo.
Section2
========
Bar.
Correct:
Section1
========
Foo.
.. _target:
Section2
========
Bar.
Correct:
Section1
========
Subsection1
-----------
Foo.
Incorrect:
Section1
========
Foo.
Section2
========
Bar.
Literal blocks¶
Use ::
on the same line as the line containing text when possible.
The literal blocks must be indented with three spaces.
Correct:
Bla bla bla::
apt-get update
Incorrect:
Bla bla bla:
::
apt-get update
Inline markup¶
Use the following roles when applicable:
:file:
for file, i.e.:The :file:`/dev/null` file.
:menuselection:
for the web interface menu:The :menuselection:`Configuration --> Management --> Certificates` page.
:guilabel:
for designating a specific GUI element:The :guilabel:`Action` column.
Others¶
There must be no warning nor error messages when building the documentation with
make html
.There should be one and only one newline character at the end of each file
There should be no trailing whitespace at the end of lines
Paragraphs must be wrapped and lines should be at most 100 characters long