You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
52 lines
1.3 KiB
ReStructuredText
52 lines
1.3 KiB
ReStructuredText
Documentation Style
|
|
===================
|
|
|
|
A brief single sentence to describe what this file contains; in this case a
|
|
description of the style to write documentation in.
|
|
|
|
Format
|
|
------
|
|
|
|
We use restructured text throughout all the documentation. You should NOT use
|
|
markdown (github-flavored or otherwise). This format was chosen partly because
|
|
Sphinx only supports RST.
|
|
|
|
|
|
Sections
|
|
--------
|
|
|
|
RST support lots of different punctuation characters for underlines on sections.
|
|
Content in the specification MUST use the same characters in order for the
|
|
complete specification to be merged correctly. These characters are:
|
|
|
|
- ``=``
|
|
- ``-``
|
|
- ``~``
|
|
- ``+``
|
|
- ``^``
|
|
- `````
|
|
- ``@``
|
|
- ``:``
|
|
|
|
If you find yourself using ``^`` or beyond, you should rethink your document
|
|
layout if possible.
|
|
|
|
TODOs
|
|
-----
|
|
|
|
Any RST file in this repository may make it onto ``matrix.org``. We do not want
|
|
``TODO`` markers visible there. For internal comments, notes, TODOs, use standard
|
|
RST comments like so::
|
|
|
|
.. TODO-Bob
|
|
There is something to do here. This will not be rendered by something like
|
|
rst2html.py so it is safe to put internal comments here.
|
|
|
|
You SHOULD put your username with the TODO so we know who to ask about it.
|
|
|
|
Line widths
|
|
-----------
|
|
|
|
We use 80 characters for line widths. This is a guideline and can be flouted IF
|
|
AND ONLY IF it makes reading more legible. Use common sense.
|