summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorPatrick Rudolph <patrick.rudolph@9elements.com>2018-09-01 17:22:20 +0200
committerPhilipp Deppenwiese <zaolin.daisuki@gmail.com>2018-09-30 03:18:25 +0000
commit3d1d966dd8866e8fd399f988b38b7ceba9f4cfee (patch)
treeb7e1feb3c264cb8b857c668370966e565df03020 /Documentation
parentffe6d5415186ece9577c3bfad6d0fc8dd653705e (diff)
downloadcoreboot-3d1d966dd8866e8fd399f988b38b7ceba9f4cfee.tar.xz
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>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/getting_started/writing_documentation.md26
1 files changed, 26 insertions, 0 deletions
diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md
index d57244a72f..0ba17e3c25 100644
--- a/Documentation/getting_started/writing_documentation.md
+++ b/Documentation/getting_started/writing_documentation.md
@@ -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