|
|
# Documentation Syntax and Style
|
|
|
|
|
|
Although this wiki is written in Markdown, the documentation itself is written in [reStructuredText](http://docutils.sourceforge.net/rst.html) because we use the [Sphinx](http://www.sphinx-doc.org/en/stable/) tool to generate the online HTML documentation.
|
|
|
|
|
|
## Links
|
|
|
|
|
|
We prefer using references rather than inline links. This means that the text contains marked up words or phrases that refer to a resource elsewhere. The connection between the text and the resource is defined separately. For example:
|
|
|
```
|
|
|
The development boards for the Librem 5 are built around the `EmCraft i.MX 8M SoM`_,
|
|
|
a development platform based on the i.MX8 CPU.
|
|
|
|
|
|
.. _`EmCraft i.MX 8M SoM`: https://www.emcraft.com/products/868
|
|
|
```
|
|
|
These can be defined in the document where they are used, but commonly used resources should be collected in the `links.rst` file at the root of the repository. Documents that need to refer to these definitions can include them like this:
|
|
|
```
|
|
|
.. include:: /links.rst
|
|
|
```
|
|
|
If a link in a document requires generic text, such as in the following example, then the resource should be defined in the same document.
|
|
|
```
|
|
|
The `latest documentation`_ for Builder describes the `preferred installation`_
|
|
|
method for the IDE.
|
|
|
```
|
|
|
We don't want to include definitions for "latest documentation" and "preferred installation" in the global collection because they could clash with other uses of these phrases in links elsewhere in the documentation.
|
|
|
|
|
|
## Titles
|
|
|
|
|
|
The preferred style is to capitalize verbs ("Editing", "Create"), adjectives ("Large", "New"), nouns ("Board", "Image") but not articles ("the", "a"), conjunctions ("and", "or") and prepositions ("with", "for"). If capitalizing a word makes its meaning unclear, or it refers to a command, then it should be used verbatim (as is) and not capitalized.
|
|
|
|
|
|
This isn't critical but it makes the documentation a bit more consistent. |
|
|
\ No newline at end of file |