Documentation: Describe recommonmark's auto_toc_tree

Explain recommonmark's auto_toc_tree and give an example to make writing
documentation easier. Show an example what happens if the document
isn't included in any toctree.

Change-Id: I4938d8d292ea890caec6d396b4fa04da65e398f4
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/28427
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Tom Hiller <thrilleratplay@gmail.com>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
This commit is contained in:
Patrick Rudolph 2018-09-01 17:22:20 +02:00 committed by Philipp Deppenwiese
parent ffe6d54151
commit 3d1d966dd8
1 changed files with 26 additions and 0 deletions

View File

@ -74,6 +74,32 @@ code block to write tables in reStructuredText and embed them into the markdown:
+------------+------------+-----------+
``` #just a code block is enough
## TocTree
To make sure that all documents are included into the final documentation, you
must reference each document from at least one *toctree*. The *toctree* must
only reference files in the same folder or in subfolders !
To create a toctree, simply use a bullet list or numbered list with a single
reference. References in regular text aren't considered as *toctree* .
This feature is enabled by recommonmark's *enable_auto_toc_tree* .
**Example toctree:**
```
* [Chapter 1](chapter1.md)
* [Chapter 2](chapter2.md)
* [Subchapter](sub/index.md)
```
```
1. [Chapter 1](chapter1.md)
2. [Chapter 2](chapter2.md)
```
If you do only reference the document, but do not include it in any toctree,
you'll see the following warning:
**WARNING: document isn't included in any toctree**
[coreboot]: https://coreboot.org
[Documentation]: https://review.coreboot.org/cgit/coreboot.git/tree/Documentation
[shpinx-autobuild]: https://github.com/GaretJax/sphinx-autobuild