From 3d1d966dd8866e8fd399f988b38b7ceba9f4cfee Mon Sep 17 00:00:00 2001 From: Patrick Rudolph Date: Sat, 1 Sep 2018 17:22:20 +0200 Subject: 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 Reviewed-on: https://review.coreboot.org/28427 Tested-by: build bot (Jenkins) Reviewed-by: Tom Hiller Reviewed-by: Philipp Deppenwiese --- .../getting_started/writing_documentation.md | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'Documentation/getting_started/writing_documentation.md') 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 -- cgit v1.2.3