summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorYujun Zhang <zhang.yujunz@zte.com.cn>2017-04-02 09:05:46 +0800
committerYujun Zhang <zhang.yujunz@zte.com.cn>2017-04-02 09:05:46 +0800
commit8ed573c27d67bdc7bead88e960f23bdb5f0f88b0 (patch)
tree789800d771dfc8ef705836618bb0e42314fadb8c
parent9e4d243f1360158555fe92cc35fae6521bfdfce5 (diff)
Add more comprehensive document example
Change-Id: Ia414c692c7f91c4e071cdb4fb19637eb10adf11c Signed-off-by: Yujun Zhang <zhang.yujunz@zte.com.cn>
-rw-r--r--CONTRIBUTING.md9
-rw-r--r--docs/example/chapter.rst118
-rw-r--r--docs/example/index.rst12
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