Merge "Add more comprehensive document example"

3 files changed, 131 insertions, 8 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 03420986..9e73df14 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -98,14 +98,7 @@ Documentation
 The documents are built automatically by sphinx from reStructuredText (reST).
 Please read [reStructuredText Primer][rp] if you are not familiar with it.
 
-A cheat sheet for headings are as following
-
-* `#` with overline, for parts
-* `*` with overline, for chapters
-* `=`, for sections
-* `-`, for subsections
-* `^`, for subsubsections
-* `"`, for paragraphs
+Start a new document by copying an example from ``docs/example``
 
 Frequent Asked Questions
 ------------------------
diff --git a/docs/example/chapter.rst b/docs/example/chapter.rst
new file mode 100644
index 00000000..16a31d00
--- /dev/null
+++ b/docs/example/chapter.rst
@@ -0,0 +1,118 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+*************
+Chapter Title
+*************
+
+There is more than one way to write reStructuredText, the following markups are most common in QTIP documentation.
+
+Section
+=======
+
+Subsection
+----------
+
+Subsubsection
+^^^^^^^^^^^^^
+
+Paragraph
+"""""""""
+
+Markups
+=======
+
+Inline
+------
+
+The standard reST inline markup is quite simple: use
+
+* one asterisk: *text* for emphasis (italics),
+* two asterisks: **text** for strong emphasis (boldface), and
+* backquotes: ``text`` for code samples.
+
+List
+----
+
+* This is a bulleted list.
+* It has two items, the second
+ item uses two lines.
+
+1. This is a numbered list.
+2. It has two items too.
+
+#. This is a numbered list.
+#. It has two items too.
+
+
+Nested lists, note the blank lines after parent list items
+
+* this is
+* a list
+
+  * with a nested list
+  * and some subitems
+
+* and here the parent list continues
+
+Code
+----
+
+Start a code blocks with double colon::
+
+    paths:
+      /plans/{name}:
+        get:
+          summary: Get a plan by plan name
+          operationId: qtip.api.controllers.plan.get_plan
+
+Note the code block must be indented.
+
+Or create one explicitly and specify the language
+
+.. code-block:: python
+
+    @common.check_endpoint_for_error(resource='Plan')
+    def get_plan(name):
+        plan_spec = plan.Plan(name)
+        return plan_spec.content
+
+
+
+Tables
+------
+
+Grid Table
+^^^^^^^^^^
+
++------------------------+------------+----------+----------+
+| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+| (header rows optional) |            |          |          |
++========================+============+==========+==========+
+| body row 1, column 1   | column 2   | column 3 | column 4 |
++------------------------+------------+----------+----------+
+| body row 2             | ...        | ...      |          |
++------------------------+------------+----------+----------+
+
+Simple tables
+^^^^^^^^^^^^^
+
+Limited to one line per row
+
+=====  =====  =======
+A      B      A and B
+=====  =====  =======
+False  False  False
+True   False  False
+False  True   False
+True   True   True
+=====  =====  =======
+
+Hyperlinks
+----------
+
+Create `hyperlinks`_ and list them separately at the end of section or chapter
+
+.. _hyperlinks: http://example.com
+
diff --git a/docs/example/index.rst b/docs/example/index.rst
new file mode 100644
index 00000000..31cd3a4c
--- /dev/null
+++ b/docs/example/index.rst
@@ -0,0 +1,12 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+==========
+Part Title
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   chapter.rst