diff options
author | James Ennis <james.ennis@codethink.com> | 2018-04-16 16:06:28 +0100 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-04-18 23:16:02 +0900 |
commit | fd9ee86035afed3b4a9981a704f5d7bf0cabc1d4 (patch) | |
tree | 52a889471276c425679710a851102f2ee20053cb /HACKING.rst | |
parent | ee7e89d2dc939447d9638d93f81e83b4701a755c (diff) | |
download | buildstream-fd9ee86035afed3b4a9981a704f5d7bf0cabc1d4.tar.gz |
HACKING.rst: Include Documentation Formatting Policy
Diffstat (limited to 'HACKING.rst')
-rw-r--r-- | HACKING.rst | 23 |
1 files changed, 22 insertions, 1 deletions
diff --git a/HACKING.rst b/HACKING.rst index 8f5a801a9..b0bc2cb3b 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -218,7 +218,28 @@ Useful links: * rst primer: http://www.sphinx-doc.org/en/stable/rest.html -Building docs +Documentation formatting policy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The BuildStream documentation style is as follows: + +* Titles and headings require two leading empty lines above them. Only the first word should be capitalized. + + * If there is an ``.. _internal_link`` anchor, there should be two empty lines above the anchor, followed by one leading empty line. + +* Within a section, paragraphs should be separated by one empty line. + +* Notes are defined using: ``.. note::`` blocks, followed by an empty line and then indented (3 spaces) text. + +* Code blocks are defined using: ``.. code:: LANGUAGE`` blocks, followed by an empty line and then indented (3 spaces) text. Note that the default language is `python`. + +* Cross references should be of the form ``:role:`target```. + + * To cross reference arbitrary locations with, for example, the anchor ``_anchor_name``, you must give the link an explicit title: ``:ref:`Link text <anchor_name>```. Note that the "_" prefix is not required. + +For further information, please see the `Sphinx Documentation <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. + + +Building Docs ~~~~~~~~~~~~~ The documentation build is not integrated into the ``setup.py`` and is difficult (or impossible) to do so, so there is a little bit of setup |