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 documenation 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 ### Install Sphinx
  18
  19 Please follow this official [guide] to install sphinx.
  20 You will also need python-recommonmark for sphinx to be able to handle
  21 markdown documenation.
  22
  23 The recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and
  24 recommonmark 0.4.0.
  25
  26 ### Optional
  27
  28 Install [shpinx-autobuild] for rebuilding markdown/rst sources on the fly!
  29
  30 ## Basic and simple rules
  31
  32 The following rules should be followed in order to get it at least reviewed
  33 on [review.coreboot.org].
  34
  35 Documentation:
  36
  37 1.  Must be written in **markdown** with **embedded reStructuredText**
  38     format.
  39 2.  Must be written in **English**.
  40 3.  Must be placed into **Documentation/** directory subfolder.
  41 4.  Should follow the same directory structure as **src/** when practical.
  42 5.  Must be referenced from within other markdown files
  43 6.  The commit must follow the [Gerrit Guidelines].
  44 7.  Must have all **lowercase filenames**.
  45 8.  Running text should have a visible width of about **72 chars**.
  46 9.  Should not **duplicate** documentation, but reference it instead.
  47 10.  Must not include the same picture in multiple markdown files.
  48 11.  Images should be kept small. They should be under 700px in width, as
  49      the current theme doesn't allow bigger images.
  50 12.  Shouldn't cover implementation details; for details, the code is the
  51      reference.
  52
  53 ## Referencing markdown documents
  54
  55 Starting with Sphinx 1.6 recommonmark's *auto_doc_ref* feature is broken.
  56 To reference documents use the TOC tree or inline RST code.
  57
  58 ## Markdown and Tables
  59
  60 Under Sphinx markdown tables are not supported. Therefore you can use following
  61 code block to write tables in reStructuredText and embed them into the markdown:
  62
  63     ```eval_rst
  64     +------------+------------+-----------+
  65     | Header 1   | Header 2   | Header 3  |
  66     +============+============+===========+
  67     | body row 1 | column 2   | column 3  |
  68     +------------+------------+-----------+
  69     | body row 2 | Cells may span columns.|
  70     +------------+------------+-----------+
  71     | body row 3 | Cells may  | - Cells   |
  72     +------------+ span rows. | - contain |
  73     | body row 4 |            | - blocks. |
  74     +------------+------------+-----------+
  75     ``` #just a code block is enough
  76
  77 ## TocTree
  78
  79 To make sure that all documents are included into the final documentation, you
  80 must reference each document from at least one *toctree*. The *toctree* must
  81 only reference files in the same folder or in subfolders !
  82 To create a toctree, simply use a bullet list or numbered list with a single
  83 reference. References in regular text aren't considered as *toctree* .
  84 This feature is enabled by recommonmark's *enable_auto_toc_tree* .
  85
  86 **Example toctree:**
  87
  88 ```
  89 * [Chapter 1](chapter1.md)
  90 * [Chapter 2](chapter2.md)
  91 * [Subchapter](sub/index.md)
  92 ```
  93
  94 ```
  95 1. [Chapter 1](chapter1.md)
  96 2. [Chapter 2](chapter2.md)
  97 ```
  98
  99 If you do only reference the document, but do not include it in any toctree,
 100 you'll see the following warning:
 101 **WARNING: document isn't included in any toctree**
 102
 103 [coreboot]: https://coreboot.org
 104 [Documentation]: https://review.coreboot.org/cgit/coreboot.git/tree/Documentation
 105 [shpinx-autobuild]: https://github.com/GaretJax/sphinx-autobuild
 106 [guide]: http://www.sphinx-doc.org/en/stable/install.html
 107 [Sphinx]: http://www.sphinx-doc.org/en/master/
 108 [Markdown Guide]: https://www.markdownguide.org/
 109 [Gerrit Guidelines]: https://doc.coreboot.org/gerrit_guidelines.html
 110 [review.coreboot.org]: https://review.coreboot.org