[coreboot-gerrit] Change in coreboot[master]: Documentation: Update index.md for more structure.

[Philipp Deppenwiese (Code Review)]

Philipp Deppenwiese has uploaded this change for review. ( https://review.coreboot.org/26262


Change subject: Documentation: Update index.md for more structure.
......................................................................

Documentation: Update index.md for more structure.

* Introduce more information about the
  documentation process in general.
* Move getting started and lessons
  into sub-directories.

Change-Id: I78c3ec0e8bcc342686277ae141a88d0486680978
Signed-off-by: Philipp Deppenwiese <zaolin at das-labor.org>
---
R Documentation/getting_started/build_system.md
R Documentation/getting_started/gerrit_guidelines.md
A Documentation/getting_started/index.md
R Documentation/getting_started/kconfig.md
R Documentation/getting_started/submodules.md
M Documentation/index.md
A Documentation/lessons/index.md
R Documentation/lessons/lesson2.md
8 files changed, 59 insertions(+), 14 deletions(-)



  git pull ssh://review.coreboot.org:29418/coreboot refs/changes/62/26262/1

diff --git a/Documentation/build_system.md b/Documentation/getting_started/build_system.md
similarity index 100%
rename from Documentation/build_system.md
rename to Documentation/getting_started/build_system.md
diff --git a/Documentation/gerrit_guidelines.md b/Documentation/getting_started/gerrit_guidelines.md
similarity index 100%
rename from Documentation/gerrit_guidelines.md
rename to Documentation/getting_started/gerrit_guidelines.md
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md
new file mode 100644
index 0000000..b23e89d
--- /dev/null
+++ b/Documentation/getting_started/index.md
@@ -0,0 +1,6 @@
+# Getting Started
+
+* [Build System](build_system.md)
+* [Submodules](submodules.md)
+* [Kconfig](kconfig.md)
+* [Gerrit Guidelines](gerrit_guidelines.md)
diff --git a/Documentation/core/Kconfig.md b/Documentation/getting_started/kconfig.md
similarity index 100%
rename from Documentation/core/Kconfig.md
rename to Documentation/getting_started/kconfig.md
diff --git a/Documentation/submodules.md b/Documentation/getting_started/submodules.md
similarity index 100%
rename from Documentation/submodules.md
rename to Documentation/getting_started/submodules.md
diff --git a/Documentation/index.md b/Documentation/index.md
index 8354786..8e9e6bf 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -1,21 +1,57 @@
-Welcome to coreboot's documentation!
-====================================
+# Welcome to the coreboot documentation
 
 This is the developer documentation for [coreboot](https://coreboot.org).
 It is built from Markdown files in the
 [Documentation](https://review.coreboot.org/cgit/coreboot.git/tree/Documentation)
 directory in the source code.
 
-Contents:
+## How to write documentation
 
-* [Lesson 2: Submitting a patch to coreboot.org](Lesson2.md)
-* [Gerrit Etiquette and Guidelines](gerrit_guidelines.md)
-* [coreboot's build system](build_system.md)
-* [Kconfig in coreboot](core/Kconfig.md)
-* [Use of git submodules in coreboot](submodules.md)
-* [Timestamps](timestamp.md)
-* [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)
-* [ABI data consumption](abi-data-consumption.md)
-* [GPIO toggling in ACPI AML](acpi/gpio.md)
-* [Native Graphics Initialization with libgfxinit](gfx/libgfxinit.md)
-* [Sandy Bridge Raminit](Intel/NativeRaminit/Sandybridge.md)
+> Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.
+
+That said please always try to write documentation! One problem in the firmware development is the missing documentation. In this document you will get a brief introduction how to write, submit and publish documenation to coreboot.
+
+## Preparations
+coreboot uses [Sphinx](http://www.sphinx-doc.org/en/master/) as documentation tool. We prefer the markdown format over reStructuredText so only embedded ReST is supported. Checkout the [Markdown Guide](https://www.markdownguide.org/)
+for more information
+
+### Install Sphinx
+Please follow this official [guide](http://www.sphinx-doc.org/en/stable/install.html).
+
+### Optional
+Install [shinx-autobuild](https://github.com/GaretJax/sphinx-autobuild) for rebuilding markdown/rst sources on the fly!
+
+## Basic and simple rules
+The following rules must be followed in order to get it at least reviewed on review.coreboot.org.
+
+Documentation:
+
+1) Must be written in __markdown__ or __embedded reStructuredText__ format.
+2) Must be written in the __English__.
+3) Must be placed into __Documentation/__ directory subfolders which must have the same directory structure as the code under __src/__
+4) Must be linked/included into higher markdown files if sections are used.
+5) Follow the [Gerrit Guidelines](https://doc.coreboot.org/gerrit_guidelines.html).
+
+## Markdown and Tables
+Under Sphinx markdown tables are not supported. Therefore you can use following code block to write tables in reStructuredText and embed them into the markdown:
+
+```
+```eval_rst
++------------+------------+-----------+
+| Header 1   | Header 2   | Header 3  |
++============+============+===========+
+| body row 1 | column 2   | column 3  |
++------------+------------+-----------+
+| body row 2 | Cells may span columns.|
++------------+------------+-----------+
+| body row 3 | Cells may  | - Cells   |
++------------+ span rows. | - contain |
+| body row 4 |            | - blocks. |
++------------+------------+-----------+
+``` #just a code block is enough
+```
+
+Content:
+
+1) [Getting Started](getting_started/index.md)
+2) [Rookie Guide](lessons/index.md)
diff --git a/Documentation/lessons/index.md b/Documentation/lessons/index.md
new file mode 100644
index 0000000..94acaa0
--- /dev/null
+++ b/Documentation/lessons/index.md
@@ -0,0 +1,3 @@
+# Rookie Guide
+
+* [Lesson 2](lesson2.md)
diff --git a/Documentation/Lesson2.md b/Documentation/lessons/lesson2.md
similarity index 100%
rename from Documentation/Lesson2.md
rename to Documentation/lessons/lesson2.md

-- 
To view, visit https://review.coreboot.org/26262
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: I78c3ec0e8bcc342686277ae141a88d0486680978
Gerrit-Change-Number: 26262
Gerrit-PatchSet: 1
Gerrit-Owner: Philipp Deppenwiese <zaolin.daisuki at gmail.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/coreboot-gerrit/attachments/20180513/73c43cd3/attachment-0001.html>