From 1957b7e8f05c7fbad42f78b61799b67d6d80ae88 Mon Sep 17 00:00:00 2001 From: Martin Kopec Date: Fri, 7 Dec 2018 15:54:56 +0100 Subject: [PATCH] Create basic doc structure Create doc structure which follows OpenStack guidelines: https://docs.openstack.org/doc-contrib-guide/project-guides.html The patch also fixes a few typos including too long lines. Change-Id: I80407f300ccb5efb01e82cac7b75063bc2f3ffec --- CONTRIBUTING.rst | 58 ++++++++++++++++--------- doc/source/contributor/contributing.rst | 1 + doc/source/contributor/index.rst | 8 ++++ doc/source/index.rst | 32 ++++---------- doc/source/overview.rst | 5 +++ doc/source/user/default.rst | 7 +++ doc/source/user/index.rst | 9 ++++ doc/source/user/usage.rst | 25 +++++++++++ 8 files changed, 100 insertions(+), 45 deletions(-) create mode 120000 doc/source/contributor/contributing.rst create mode 100644 doc/source/contributor/index.rst create mode 100644 doc/source/overview.rst create mode 100644 doc/source/user/default.rst create mode 100644 doc/source/user/index.rst create mode 100644 doc/source/user/usage.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index afd3d94c..2f3fac2c 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,51 +1,61 @@ -os_tempest -########## -:tags: openstack, cloud, ansible -:category: \*nix +Contributor Guide +================= -contributor guidelines -^^^^^^^^^^^^^^^^^^^^^^ +:tags: openstack, cloud, ansible, os_tempest +:category: \*nix Filing Bugs ----------- -Bugs should be filed on Launchpad, not GitHub: "https://bugs.launchpad.net/openstack-ansible" +Bugs should be filed or Launchpad_, **not GitHub.** +.. _Launchpad: https://bugs.launchpad.net/openstack-ansible -When submitting a bug, or working on a bug, please ensure the following criteria are met: - * The description clearly states or describes the original problem or root cause of the problem. +When submitting a bug, or working on a bug, please ensure the following +criteria are met: + + * The description clearly states or describes the original problem or root + cause of the problem. * Include historical information on how the problem was identified. * Any relevant logs are included. - * The provided information should be totally self-contained. External access to web services/sites should not be needed. + * The provided information should be totally self-contained. External + access to web services/sites should not be needed. * Steps to reproduce the problem if possible. Submitting Code --------------- -Changes to the project should be submitted for review via the Gerrit tool, following -the workflow documented at: "http://docs.openstack.org/infra/manual/developers.html#development-workflow" +Changes to the project should be submitted for review via the Gerrit tool, +following the workflow documented at: +http://docs.openstack.org/infra/manual/developers.html#development-workflow -Pull requests submitted through GitHub will be ignored and closed without regard. +Pull requests submitted through GitHub will be ignored and closed without +regard. Extra ----- Tags: - If it's a bug that needs fixing in a branch in addition to Master, add a '\-backport-potential' tag (eg ``juno-backport-potential``). There are predefined tags that will autocomplete. + If it's a bug that needs fixing in a branch in addition to Master, add a + '\-backport-potential' tag (eg ``juno-backport-potential``). + There are predefined tags that will autocomplete. Status: Please leave this alone, it should be New till someone triages the issue. Importance: - Should only be touched if it is a Blocker/Gating issue. If it is, please set to High, and only use Critical if you have found a bug that can take down whole infrastructures. + Should only be touched if it is a Blocker/Gating issue. If it is, please + set to High, and only use Critical if you have found a bug that can take + down whole infrastructures. Style guide ----------- -When creating tasks and other roles for use in Ansible please create then using the YAML dictionary format. +When creating tasks and other roles for use in Ansible please create then using +the YAML dictionary format. Example YAML dictionary format: .. code-block:: yaml @@ -69,17 +79,23 @@ Example **NOT** in YAML dictionary format: - some-other-tag -Usage of the ">" and "|" operators should be limited to Ansible conditionals and command modules such as the ansible ``shell`` module. +Usage of the ">" and "|" operators should be limited to Ansible conditionals +and command modules such as the ansible ``shell`` module. Issues ------ -When submitting an issue, or working on an issue please ensure the following criteria are met: - * The description clearly states or describes the original problem or root cause of the problem. +When submitting an issue, or working on an issue please ensure the following +criteria are met: + + * The description clearly states or describes the original problem or root + cause of the problem. * Include historical information on how the problem was identified. * Any relevant logs are included. - * If the issue is a bug that needs fixing in a branch other than Master, add the 'backport potential' tag TO THE ISSUE (not the PR). - * The provided information should be totally self-contained. External access to web services/sites should not be needed. + * If the issue is a bug that needs fixing in a branch other than Master, + add the 'backport potential' tag TO THE ISSUE (not the PR). + * The provided information should be totally self-contained. External + access to web services/sites should not be needed. * If the issue is needed for a hotfix release, add the 'expedite' label. * Steps to reproduce the problem if possible. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 120000 index 00000000..ac9338fc --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1 @@ +../../../CONTRIBUTING.rst \ No newline at end of file diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 00000000..a28f816a --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,8 @@ +Contributor Guide +================= + +.. toctree:: + :maxdepth: 2 + :includehidden: + + contributing diff --git a/doc/source/index.rst b/doc/source/index.rst index 00331d42..f0aa4958 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -7,31 +7,15 @@ This is the Ansible role to deploy OpenStack Tempest. :tags: openstack, cloud, ansible, os_tempest :category: \*nix -Basic role example -~~~~~~~~~~~~~~~~~~ +Content: +-------- -.. code-block:: yaml +.. toctree:: + :maxdepth: 3 - - role: "os_tempest" - ROLE_VARS... + overview + user/index + contributor/index -To clone or view the source code for this repository, visit the role repository -for `os_tempest `_. -Default variables -~~~~~~~~~~~~~~~~~ - -.. literalinclude:: ../../defaults/main.yml - :language: yaml - :start-after: under the License. - -Dependencies -~~~~~~~~~~~~ - -This role needs pip >= 7.1 installed on the target host. - -Example playbook -~~~~~~~~~~~~~~~~ - -.. literalinclude:: ../../examples/playbook.yml - :language: yaml +* :ref:`search` diff --git a/doc/source/overview.rst b/doc/source/overview.rst new file mode 100644 index 00000000..9382d412 --- /dev/null +++ b/doc/source/overview.rst @@ -0,0 +1,5 @@ +======== +Overview +======== + +.. include:: ../../README.rst diff --git a/doc/source/user/default.rst b/doc/source/user/default.rst new file mode 100644 index 00000000..b1c99d2a --- /dev/null +++ b/doc/source/user/default.rst @@ -0,0 +1,7 @@ +================= +Default variables +================= + +.. literalinclude:: ../../../defaults/main.yml + :language: yaml + :start-after: under the License. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 00000000..cbfcde72 --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,9 @@ +User Guide +========== + +.. toctree:: + :maxdepth: 2 + :includehidden: + + usage + default diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst new file mode 100644 index 00000000..db033f39 --- /dev/null +++ b/doc/source/user/usage.rst @@ -0,0 +1,25 @@ +===== +Usage +===== + +Basic role example +------------------ + +.. code-block:: yaml + + - role: "os_tempest" + ROLE_VARS... + +To clone or view the source code for this repository, visit the role repository +for `os_tempest `_. + +Dependencies +------------ + +This role needs pip >= 7.1 installed on the target host. + +Example playbook +---------------- + +.. literalinclude:: ../../../examples/playbook.yml + :language: yaml