[coreboot-gerrit] Change in coreboot[master]: Documentation: Describe recommonmark's auto_toc_tree

[Patrick Rudolph (Code Review)]

Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/28427


Change subject: Documentation: Describe recommonmark's auto_toc_tree
......................................................................

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 at 9elements.com>
---
M Documentation/getting_started/writing_documentation.md
1 file changed, 26 insertions(+), 0 deletions(-)



  git pull ssh://review.coreboot.org:29418/coreboot refs/changes/27/28427/1

diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md
index 027def9..4431cda 100644
--- a/Documentation/getting_started/writing_documentation.md
+++ b/Documentation/getting_started/writing_documentation.md
@@ -66,6 +66,32 @@
     +------------+------------+-----------+
     ``` #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

-- 
To view, visit https://review.coreboot.org/28427
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings

Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-MessageType: newchange
Gerrit-Change-Id: I4938d8d292ea890caec6d396b4fa04da65e398f4
Gerrit-Change-Number: 28427
Gerrit-PatchSet: 1
Gerrit-Owner: Patrick Rudolph <patrick.rudolph at 9elements.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/coreboot-gerrit/attachments/20180901/652161d9/attachment-0001.html>