diff options
| -rw-r--r-- | CONTRIBUTING.md | 9 | ||||
| -rw-r--r-- | docs/example/chapter.rst | 118 | ||||
| -rw-r--r-- | docs/example/index.rst | 12 | ||||
| -rw-r--r-- | docs/testing/developer/devguide/overview.rst | 50 |
4 files changed, 181 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 diff --git a/docs/testing/developer/devguide/overview.rst b/docs/testing/developer/devguide/overview.rst index 1d7e22fe..66712155 100644 --- a/docs/testing/developer/devguide/overview.rst +++ b/docs/testing/developer/devguide/overview.rst @@ -79,6 +79,48 @@ The test cases are written in `pytest`_. You may run it selectively with pytest tests/unit/reporter + +Branching +========= + +Stable branches are created when features are frozen for next release. According to +`OPNFV release milestone description`_, stable branch window is open on MS6 and closed on MS7. + +#. Contact gerrit admin <opnfv-helpdesk@rt.linuxfoundation.org> to create branch for project. +#. Setup `qtip jobs`_ and `docker jobs`_ for stable branch in releng +#. Follow `instructions for stable branch`_. + +NOTE: we do **NOT** create branches for feature development as in the popular `GitHub Flow`_ + + +Releasing +========= + +Tag Deliverable and write release note + +Git repository +-------------- + +Follow the example in `Git Tagging Instructions for Danube`_ to tag the source code:: + + git fetch gerrit + git checkout stable/<release-name> + git tag -am "<release-version>" <release-version> + git push gerrit <release-version> + +Docker image +------------ + +#. Login `OPNFV Jenkins`_ +#. Go to the `qtip-docker-build-push-<release>`_ and click "Build With Parameters" +#. Fill in ``RELEASE_VERSION`` with version number not including release name, e.g. ``1.0`` +#. Trigger a manual build + +Release note +------------ + +Create release note under ``qtip/docs/release/release-notes`` and update ``index.rst`` + .. _Connexion: https://pypi.python.org/pypi/connexion/ .. _Click: http://click.pocoo.org/ .. _Jinja2: http://jinja.pocoo.org/ @@ -87,3 +129,11 @@ The test cases are written in `pytest`_. You may run it selectively with .. _sphinx: http://www.sphinx-doc.org/en/stable/ .. _The Hitchhiker's Guide to Python: http://python-guide-pt-br.readthedocs.io/en/latest/writing/structure/ .. _tox: https://tox.readthedocs.io/ +.. _OPNFV release milestone description: https://wiki.opnfv.org/display/SWREL/Release+Milestone+Description +.. _qtip jobs: https://git.opnfv.org/releng/tree/jjb/qtip/ +.. _docker jobs: https://git.opnfv.org/releng/tree/jjb/releng/opnfv-docker.yml +.. _instructions for stable branch: https://wiki.opnfv.org/display/SWREL/Stablebranch +.. _GitHub Flow: https://guides.github.com/introduction/flow/ +.. _Git Tagging Instructions for Danube: https://wiki.opnfv.org/display/SWREL/Git+Tagging+Instructions+for+Danube +.. _OPNFV Jenkins: https://build.opnfv.org/ci/view/qtip/ +.. _docker build job: https://build.opnfv.org/ci/view/qtip/job/qtip-docker-build-push-danube/ |