Documentation/getting_started/writing_documentation.md

   1 # coreboot documentation guidelines
   2
   3 > Documentation is like sex: when it is good, it is very, very good;
   4 > and when it is bad, it is better than nothing.
   5
   6 That said please always try to write documentation! One problem in the
   7 firmware development is the missing documentation. In this document
   8 you will get a brief introduction how to write, submit and publish
   9 documentation to coreboot.
  10
  11 ## Preparations
  12
  13 coreboot uses [Sphinx] documentation tool. We prefer the markdown format
  14 over reStructuredText so only embedded ReST is supported. Checkout the
  15 [Markdown Guide] for more information.
  16
  17 ### option 1: Use the docker image
  18
  19 The easiest way to build the documentation is using a docker image.
  20 To build the image run the following in the base directory:
  21
  22         make -C util/docker/ doc.coreboot.org
  23
  24 Before building the documentation make sure the output directory is given
  25 the correct permissions before running docker.
  26
  27         mkdir -p Documentation/_build
  28
  29 To build the documentation:
  30
  31         make -C util/docker docker-build-docs
  32
  33 To have the documentation build and served over a web server live run:
  34
  35         make -C util/docker docker-livehtml-docs
  36
  37 On the host machine, open a browser to the address <http://0.0.0.0:8000>.
  38
  39 ### option 2: Install Sphinx
  40
  41 Please follow this official [guide] to install sphinx.
  42 You will also need python-recommonmark for sphinx to be able to handle
  43 markdown documentation.
  44
  45 Since some Linux distributions don't package every needed sphinx extension,
  46 the installation via pip in a venv is recommended. You'll need these python3
  47 modules:
  48
  49 * sphinx
  50 * recommonmark
  51 * sphinx_rtd_theme
  52 * sphinxcontrib-ditaa
  53
  54 The following combination of versions has been tested: sphinx 2.3.1,
  55 recommonmark 0.6.0, sphinx_rtd_theme 0.4.3 and sphinxcontrib-ditaa 0.7.
  56
  57 Now change into the `Documentation` folder in the coreboot directory and run
  58 this command in there
  59
  60         make sphinx
  61
  62 If no error occurs, you can find the generated HTML documentation in
  63 `Documentation/_build` now.
  64
  65 ### Optional
  66
  67 Install [sphinx-autobuild] for rebuilding markdown/rst sources on the fly!
  68
  69 ## Basic and simple rules
  70
  71 The following rules should be followed in order to get it at least reviewed
  72 on [review.coreboot.org].
  73
  74 Documentation:
  75
  76 1.  Must be written in **markdown** with **embedded reStructuredText**
  77     format.
  78 2.  Must be written in **English**.
  79 3.  Must be placed into **Documentation/** directory subfolder.
  80 4.  Should follow the same directory structure as **src/** when practical.
  81 5.  Must be referenced from within other markdown files
  82 6.  The commit must follow the [Gerrit Guidelines].
  83 7.  Must have all **lowercase filenames**.
  84 8.  Running text should have a visible width of about **72 chars**.
  85 9.  Should not **duplicate** documentation, but reference it instead.
  86 10.  Must not include the same picture in multiple markdown files.
  87 11.  Images should be kept small. They should be under 700px in width, as
  88      the current theme doesn't allow bigger images.
  89 12.  Shouldn't cover implementation details; for details, the code is the
  90      reference.
  91
  92 ## Referencing markdown documents
  93
  94 Starting with Sphinx 1.6 recommonmark's *auto_doc_ref* feature is broken.
  95 To reference documents use the TOC tree or inline RST code.
  96
  97 ## Markdown and Tables
  98
  99 Under Sphinx markdown tables are not supported. Therefore you can use following
 100 code block to write tables in reStructuredText and embed them into the markdown:
 101
 102     ```eval_rst
 103     +------------+------------+-----------+
 104     | Header 1   | Header 2   | Header 3  |
 105     +============+============+===========+
 106     | body row 1 | column 2   | column 3  |
 107     +------------+------------+-----------+
 108     | body row 2 | Cells may span columns.|
 109     +------------+------------+-----------+
 110     | body row 3 | Cells may  | - Cells   |
 111     +------------+ span rows. | - contain |
 112     | body row 4 |            | - blocks. |
 113     +------------+------------+-----------+
 114     ``` #just a code block is enough
 115
 116 ## TocTree
 117
 118 To make sure that all documents are included into the final documentation, you
 119 must reference each document from at least one *toctree*. The *toctree* must
 120 only reference files in the same folder or in subfolders !
 121 To create a toctree, simply use a bullet list or numbered list with a single
 122 reference. References in regular text aren't considered as *toctree* .
 123 This feature is enabled by recommonmark's *enable_auto_toc_tree* .
 124
 125 **Example toctree:**
 126
 127 ```
 128 * [Chapter 1](chapter1.md)
 129 * [Chapter 2](chapter2.md)
 130 * [Subchapter](sub/index.md)
 131 ```
 132
 133 ```
 134 1. [Chapter 1](chapter1.md)
 135 2. [Chapter 2](chapter2.md)
 136 ```
 137
 138 If you do only reference the document, but do not include it in any toctree,
 139 you'll see the following warning:
 140 **WARNING: document isn't included in any toctree**
 141
 142 ## CSV
 143
 144 You can import CSV files and let sphinx automatically convert them to human
 145 readable tables, using the following reStructuredText snipped:
 146
 147     ```eval_rst
 148     .. csv-table::
 149        :header: "Key", "Value"
 150        :file: keyvalues.csv
 151     ```
 152
 153 Of course this can only be done from a markdown file that is included in the
 154 TOC tree.
 155
 156 [coreboot]: https://coreboot.org
 157 [Documentation]: https://review.coreboot.org/cgit/coreboot.git/tree/Documentation
 158 [sphinx-autobuild]: https://github.com/GaretJax/sphinx-autobuild
 159 [guide]: http://www.sphinx-doc.org/en/stable/install.html
 160 [Sphinx]: http://www.sphinx-doc.org/en/master/
 161 [Markdown Guide]: https://www.markdownguide.org/
 162 [Gerrit Guidelines]: ../contributing/gerrit_guidelines.md
 163 [review.coreboot.org]: https://review.coreboot.org