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:
parent
ffe6d54151
commit
3d1d966dd8
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue