Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.
That said please always try to write documentation! One problem in the firmware development is the missing documentation. In this document you will get a brief introduction how to write, submit and publish documenation to coreboot.
coreboot uses Sphinx documentation tool. We prefer the markdown format over reStructuredText so only embedded ReST is supported. Checkout the Markdown Guide for more information.
Please follow this official guide to install sphinx. You will also need python-recommonmark for sphinx to be able to handle markdown documenation.
Install shpinx-autobuild for rebuilding markdown/rst sources on the fly!
The following rules should be followed in order to get it at least reviewed on review.coreboot.org.
Documentation:
Under Sphinx markdown tables are not supported. Therefore you can use following code block to write tables in reStructuredText and embed them into the markdown:
```eval_rst +------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+ ``` #just a code block is enough