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 6That said please always try to write documentation! One problem in the 7firmware development is the missing documentation. In this document 8you will get a brief introduction how to write, submit and publish 9documentation to coreboot. 10 11## Preparations 12 13coreboot uses [Sphinx] documentation tool. We prefer the markdown format 14over reStructuredText so only embedded ReST is supported. Checkout the 15[Markdown Guide] for more information. 16 17### option 1: Use the docker image 18 19The easiest way to build the documentation is using a docker image. 20To build the image run the following in the base directory: 21 22 make -C util/docker/ doc.coreboot.org 23 24Before building the documentation make sure the output directory is given 25the correct permissions before running docker. 26 27 mkdir -p Documentation/_build 28 29To build the documentation: 30 31 make -C util/docker docker-build-docs 32 33To have the documentation build and served over a web server live run: 34 35 make -C util/docker docker-livehtml-docs 36 37On the host machine, open a browser to the address <http://0.0.0.0:8000>. 38 39### option 2: Install Sphinx 40 41Please follow this official [guide] to install sphinx. 42You will also need python-recommonmark for sphinx to be able to handle 43markdown documentation. 44 45Since some Linux distributions don't package every needed sphinx extension, 46the installation via pip in a venv is recommended. You'll need these python3 47modules: 48 49* sphinx 50* recommonmark 51* sphinx_rtd_theme 52* sphinxcontrib-ditaa 53 54The following combination of versions has been tested: sphinx 2.3.1, 55recommonmark 0.6.0, sphinx_rtd_theme 0.4.3 and sphinxcontrib-ditaa 0.7. 56 57Now change into the `Documentation` folder in the coreboot directory and run 58this command in there 59 60 make sphinx 61 62If no error occurs, you can find the generated HTML documentation in 63`Documentation/_build` now. 64 65### Optional 66 67Install [sphinx-autobuild] for rebuilding markdown/rst sources on the fly! 68 69## Basic and simple rules 70 71The following rules should be followed in order to get it at least reviewed 72on [review.coreboot.org]. 73 74Documentation: 75 761. Must be written in **markdown** with **embedded reStructuredText** 77 format. 782. Must be written in **English**. 793. Must be placed into **Documentation/** directory subfolder. 804. Should follow the same directory structure as **src/** when practical. 815. Must be referenced from within other markdown files 826. The commit must follow the [Gerrit Guidelines]. 837. Must have all **lowercase filenames**. 848. Running text should have a visible width of about **72 chars**. 859. Should not **duplicate** documentation, but reference it instead. 8610. Must not include the same picture in multiple markdown files. 8711. Images should be kept small. They should be under 700px in width, as 88 the current theme doesn't allow bigger images. 8912. Shouldn't cover implementation details; for details, the code is the 90 reference. 91 92## Referencing markdown documents 93 94Starting with Sphinx 1.6 recommonmark's *auto_doc_ref* feature is broken. 95To reference documents use the TOC tree or inline RST code. 96 97## Markdown and Tables 98 99Under Sphinx markdown tables are not supported. Therefore you can use following 100code 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 118To make sure that all documents are included into the final documentation, you 119must reference each document from at least one *toctree*. The *toctree* must 120only reference files in the same folder or in subfolders ! 121To create a toctree, simply use a bullet list or numbered list with a single 122reference. References in regular text aren't considered as *toctree* . 123This 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``` 1341. [Chapter 1](chapter1.md) 1352. [Chapter 2](chapter2.md) 136``` 137 138If you do only reference the document, but do not include it in any toctree, 139you'll see the following warning: 140**WARNING: document isn't included in any toctree** 141 142## CSV 143 144You can import CSV files and let sphinx automatically convert them to human 145readable tables, using the following reStructuredText snipped: 146 147 ```{eval-rst} 148 .. csv-table:: 149 :header: "Key", "Value" 150 :file: keyvalues.csv 151 ``` 152 153Of course this can only be done from a markdown file that is included in the 154TOC 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 164