diff options
| -rw-r--r-- | CONTRIBUTING.md | 9 | ||||
| -rw-r--r-- | docs/example/chapter.rst | 118 | ||||
| -rw-r--r-- | docs/example/index.rst | 12 |
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 |