From ca416a4538dbbbb53f4c75dfb46e8f2b661d89db Mon Sep 17 00:00:00 2001 From: Robb Romans Date: Wed, 24 Aug 2016 16:35:52 -0500 Subject: [PATCH] [DOCS] Syntax updates to the docs Finish moving to new format, remove tags, fix RST titles, fix line lengths, add link, indent example file, fresh coat of wax. Change-Id: Ibcf3d5743c9b70d4f29ea8181d54a6c5c1974580 --- CONTRIBUTING.rst | 76 +++++++++++++++++++++++++------------------ README.rst | 30 ++++++----------- doc/source/index.rst | 36 +++++++++++++++++--- examples/playbook.yml | 10 +++--- setup.cfg | 2 +- 5 files changed, 93 insertions(+), 61 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index e989c3b1..3809d804 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,51 +1,59 @@ -TEMPLATE -######## -:tags: openstack, cloud, ansible -:category: \*nix +====================== +Contributor guidelines +====================== -contributor guidelines -^^^^^^^^^^^^^^^^^^^^^^ +Filing bugs +~~~~~~~~~~~ -Filing Bugs ------------ - -Bugs should be filed on Launchpad, not GitHub: "https://bugs.launchpad.net/openstack-ansible" +Bugs should be filed on Launchpad, not GitHub: +"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 ---------------- +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. +Tags: If it's a bug that needs fixing in a branch in addition to + Master, add a '\-backport-potential' tag (for example + ``juno-backport-potential``). There are predefined tags that will + autocomplete. Status: - Please leave this alone, it should be New till someone triages the issue. + 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, create them +using the YAML dictionary format. Example YAML dictionary format: .. code-block:: yaml @@ -69,17 +77,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, 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/README.rst b/README.rst index c8784cf8..91416318 100644 --- a/README.rst +++ b/README.rst @@ -1,22 +1,12 @@ -================================= -Ironic Role for OpenStack-Ansible -================================= +====================================================== +OpenStack-Ansible role for Bare Metal (ironic) service +====================================================== - -This is a role for the deployment of Ironic in an `OpenStack-Ansible`_ -environment. - -Please see the `role-ironic spec`_ for more details. - -.. _OpenStack-Ansible: https://github.com/openstack/openstack-ansible -.. _role-ironic spec: https://github.com/openstack/openstack-ansible-specs/blob/master/specs/mitaka/role-ironic.rst - -Tags -==== - -This role supports two tags: ``ironic-install`` and ``ironic-config`` - -The ``ironic-install`` tag can be used to install and upgrade. - -The ``ironic-config`` tag can be used to maintain configuration of the +This is an OpenStack-Ansible role to deploy the Bare Metal (ironic) service. + +Documentation for the project can be found at: + http://docs.openstack.org/developer/openstack-ansible-os_ironic + +The project home is at: + http://launchpad.net/openstack-ansible diff --git a/doc/source/index.rst b/doc/source/index.rst index feb6cb1a..14c3eb2e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,14 +1,42 @@ -================================= -Ironic role for OpenStack-Ansible -================================= +====================================================== +OpenStack-Ansible role for Bare Metal (ironic) service +====================================================== .. toctree:: :maxdepth: 2 configure-ironic.rst -Basic role example +This is an OpenStack-Ansible role to deploy the Bare Metal (ironic) +service. See the `role-ironic spec`_ for more information. + +.. _role-ironic spec: https://github.com/openstack/openstack-ansible-specs/blob/master/specs/mitaka/role-ironic.rst + + +Default variables +~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../../defaults/main.yml + :language: yaml + :start-after: under the License. + + +Required variables ~~~~~~~~~~~~~~~~~~ +None. + + +Example playbook +~~~~~~~~~~~~~~~~ + .. literalinclude:: ../../examples/playbook.yml :language: yaml + + +Tags +==== + +This role supports the ``ironic-install`` and ``ironic-config`` tags. +Use the ``ironic-install`` tag to install and upgrade. Use the +``ironic-config`` tag to maintain configuration of the service. diff --git a/examples/playbook.yml b/examples/playbook.yml index 8d85ac74..ead2da61 100644 --- a/examples/playbook.yml +++ b/examples/playbook.yml @@ -1,5 +1,5 @@ - - name: Playbook for role testing - hosts: localhost - remote_user: root - roles: - - role: openstack-ansible-ironic \ No newline at end of file +- name: Playbook for role testing + hosts: localhost + remote_user: root + roles: + - role: openstack-ansible-os_ironic diff --git a/setup.cfg b/setup.cfg index 39a054a0..bcdc6565 100644 --- a/setup.cfg +++ b/setup.cfg @@ -5,7 +5,7 @@ description-file = README.rst author = OpenStack author-email = openstack-dev@lists.openstack.org -home-page = http://www.openstack.org/ +home-page = http://docs.openstack.org/developer/openstack-ansible-os_ironic classifier = Intended Audience :: Developers Intended Audience :: System Administrators