|
|
# Librem 5 Documentation Wiki
|
|
|
|
|
|
This wiki is intended to be used to collect information about the Librem 5 phone, some of which will be used in the developer documentation stored in the associated repository. It is expected that there will also be pieces of information kept in this wiki that do not really fit in the developer documentation. |
|
|
\ No newline at end of file |
|
|
This wiki is intended to be used to collect information about the Librem 5 phone, some of which will be used in the developer documentation stored in the associated repository. It is expected that there will also be pieces of information kept in this wiki that do not really fit in the developer documentation.
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
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. |
|
|
\ No newline at end of file |