From fe8b112648174b85f0482f00f6c29d0dc23d64dc Mon Sep 17 00:00:00 2001 From: Martin Kopec Date: Wed, 8 Aug 2018 09:23:30 +0200 Subject: [PATCH] Final doc check As all of documenation parts were merged, this patch makes sure, that all of them uses the same style for marking commands, arguments, notes, ... Also a few typos were fixed. Change-Id: I0239e5241aa854f515fc2d72e7947dc51b3ecb56 Story: 2002703 Task: 22965 --- doc/source/admin/admin_usage.rst | 4 +-- doc/source/contributor/contributing.rst | 26 ++++++++-------- doc/source/install/installation.rst | 10 +++---- doc/source/user/default.rst | 6 ++-- doc/source/user/import.rst | 40 ++++++++++++------------- doc/source/user/usage.rst | 13 ++++---- 6 files changed, 51 insertions(+), 48 deletions(-) diff --git a/doc/source/admin/admin_usage.rst b/doc/source/admin/admin_usage.rst index 56915b47..059d744d 100644 --- a/doc/source/admin/admin_usage.rst +++ b/doc/source/admin/admin_usage.rst @@ -42,7 +42,7 @@ resources (`Flavors`_ and `Users`_) if they don't exist already: ``python-tempestconf`` can also create a minimal accounts file when ``--create-accounts-file`` is used. It can be useful when a user doesn't have -any and wants to create it. It can be done with one call: +any ``accounts.yaml`` and wants to create it. It can be done with one call: .. code-block:: shell-session @@ -69,7 +69,7 @@ used, `see here`_. The generated accounts file will look similarly to this one: username: admin .. note:: - More about accounts file can be in our documentation about + More about accounts file can be found in our documentation about `Usage with tempest accounts file`_ .. _Usage with tempest accounts file: ../user/usage.html#usage-with-tempest-accounts-file diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst index 0d1df9f5..872ffb52 100644 --- a/doc/source/contributor/contributing.rst +++ b/doc/source/contributor/contributing.rst @@ -2,8 +2,8 @@ How to Contribute ================= -python-tempestconf source code is publicly available. You can contribute code -to individual projects, documentation, report bugs and vulnerabilities and +``python-tempestconf`` source code is publicly available. You can contribute +code to individual projects, documentation, report bugs and vulnerabilities and request features. @@ -11,14 +11,16 @@ Reporting Bugs -------------- We have a `storyboard project `_ -created to track any change required for python-tempest. If you have found any -bug, please, report it `there `_. +created to track any change required for ``python-tempestconf``. If you have +found any bug, please, report it +`there `_. **Important** information **to mention**: - * **System** on which the problem occured (e.g. CentosOS, Ubuntu, ...) - * The source of python-tempestconf you have used. The **package version number** - in case of RPM or the **branch used** in case of installation from git. + * **System** on which the problem occurred (e.g. CentOS, Ubuntu, ...) + * The source of ``python-tempestconf`` you have used. The **package version + number** in case of RPM or the **branch used** in case of installation from + git. * The **exact command** with all arguments you have used. * It's always better to include the **console output** as well. @@ -40,8 +42,8 @@ Fixing bugs ----------- 1. If you have found a bug and you know how to fix it, please, check our - `storyboard project `_ for any - stories which may relate to the issue. If you haven't find any related + `storyboard project `_ for + any stories which may relate to the issue. If you haven't find any related story, please, create one. Check `Reporting Bugs`_. 2. Follow `Contributing Code`_ and submit a code review in @@ -50,15 +52,15 @@ Fixing bugs Contributing Code ----------------- -Like any other project part of OpenStack, the development of python-tempestconf -follows the OpenStack guidelines for contribution. +Like any other project part of OpenStack, the development of +``python-tempestconf`` follows the OpenStack guidelines for contribution. Learn `how to contribute into OpenStack `_. If you have made any changes in the source code, **run tests locally before posting a review**. You can do so by running tox. -If you've made any changes in the documentation (under `doc/`) run:: +If you've made any changes in the documentation (under ``doc/``) run:: $ tox -edocs diff --git a/doc/source/install/installation.rst b/doc/source/install/installation.rst index 4070a2c4..8017e447 100644 --- a/doc/source/install/installation.rst +++ b/doc/source/install/installation.rst @@ -10,7 +10,7 @@ Git $ git clone https://git.openstack.org/openstack/python-tempestconf $ cd python-tempestconf -2. Create a virtual environment using `virtualenv`:: +2. Create a virtual environment using :command:`virtualenv`:: $ virtualenv .venv $ source .venv/bin/activate @@ -20,7 +20,7 @@ Git (.venv) $ pip install . 4. *(optional)* Instead of manual installation described in steps 2 and 3 - 3 above, tox can be used for installing the requirements as well. + above, tox can be used for installing the requirements as well. To create python 2.7 environment run following:: $ tox -epy27 @@ -35,11 +35,11 @@ Git RPM Installation (RDO) ---------------------- -* python-tempestconf package can be installed as follows:: +* ``python-tempestconf`` package can be installed as follows:: $ sudo yum install python-tempestconf -* python-tempestconf is installed together with `openstack-tempest`, as +* ``python-tempestconf`` is installed together with ``openstack-tempest``, as a new dependency (starting **from** the **Ocata** release):: $ sudo yum install openstack-tempest @@ -48,6 +48,6 @@ RPM Installation (RDO) Pip installation ---------------- -Install `python-tempestconf` via pip as follows:: +Install ``python-tempestconf`` via pip as follows:: $ pip install python-tempestconf diff --git a/doc/source/user/default.rst b/doc/source/user/default.rst index 5335fdb3..58ba2303 100644 --- a/doc/source/user/default.rst +++ b/doc/source/user/default.rst @@ -2,9 +2,9 @@ Default values ============== -``python-tempestconf`` defines some options by default in order to simplify -general executions, because not so many options need to be defined in each -run of ``python-tempestconf``, for example in CI. +``python-tempestconf`` provides sensitive default values for many options in +order to simplify its usage, reducing the amount of options that needs to be +specified. Here is the list of tempest options, which are set by default: diff --git a/doc/source/user/import.rst b/doc/source/user/import.rst index afaa82c3..ebb8de05 100644 --- a/doc/source/user/import.rst +++ b/doc/source/user/import.rst @@ -2,31 +2,30 @@ Use python-tempestconf as Python module ======================================= -`python-tempestconf` can be imported and used from a different Python project. +``python-tempestconf`` can be imported and used from a different Python project. .. warning:: - The import of config_tempest is possible only when the tool is installed - from **master branch** or via pip, however, **python-tempestconf-2.0.0. - or newer has to be installed**. + The import of config_tempest is possible **only when the version of the + tool is at least 2.0.0**. Installation ++++++++++++ -See our `Install Guide`_ on how to install `python-tempestconf`. +See our `Install Guide`_ on how to install ``python-tempestconf``. .. _Install Guide: ../install/installation.html Import ++++++ -Import python-tempestconf in your project as follows: +Import ``python-tempestconf`` in your project as follows: .. code-block:: Python from config_tempest import main as tempestconf -python-tempestconf needs cloud credentials in order to create a tempest +``python-tempestconf`` needs cloud credentials in order to create a tempest configuration file. There is a helper method for obtaining cloud credentials which uses `os-client-config `_ @@ -55,9 +54,10 @@ the configuration tool: .. note:: - If `args_namespace` contains **--os-cloud** argument, the `get_cloud_creds` - method returns cloud credentials related to that cloud, otherwise, returns - credentials of the current cloud (according to the sourced credentials). + If `args_namespace` contains ``--os-cloud`` argument, the `get_cloud_creds` + method returns cloud credentials related to that cloud, otherwise, it + returns credentials of the current cloud (according to the sourced + credentials). List of arguments which may be passed to `config_tempest` @@ -89,7 +89,7 @@ List of arguments which may be passed to `config_tempest` Example implementation ++++++++++++++++++++++ -1. Save following code snippet as `example.py`: +1. Save following code snippet as ``example.py``: .. code-block:: Python @@ -99,7 +99,7 @@ Example implementation parser = argparse.ArgumentParser(description='Example implementation.') args = parser.parse_args() - # gets credentials of the current cloud according to + # get the credentials of the current cloud according to # the sourced credentials cloud_creds = tempestconf.get_cloud_creds(args) @@ -130,7 +130,7 @@ Example implementation $ source overcloud_rc -3. Run the `example.py`: +3. Run ``example.py``: .. code-block:: Bash @@ -140,8 +140,8 @@ Example implementation Example implementation with a named cloud +++++++++++++++++++++++++++++++++++++++++ -1. Let's say there is a `clouds.yaml` file located in `/etc/openstack/` with - the following content: +1. Let's say there is a ``clouds.yaml`` file located in ``/etc/openstack/`` + with the following content: .. code-block:: Bash @@ -160,7 +160,7 @@ Example implementation with a named cloud volume_api_version: '2' -2. Save following code snippet as an `example.py`: +2. Save following code snippet as ``example.py``: .. code-block:: Python @@ -173,14 +173,14 @@ Example implementation with a named cloud parser.add_argument('--os-cloud', help='Name of a named cloud.') args = parser.parse_args() - # gets credentials to the devstack cloud + # get the credentials to the devstack cloud cloud_creds = tempestconf.get_cloud_creds(args) tempestconf.config_tempest(non_admin=True, out='./etc/tempest.conf', cloud_creds=cloud_creds) -3. Run the `example.py`: +3. Run ``example.py``: .. code-block:: Bash @@ -189,5 +189,5 @@ Example implementation with a named cloud .. note:: In this example you **don't need** to source cloud credentials. The - credentials are obtained from the `/etc/openstack/clouds.yaml` - thanks to `--os-cloud` argument. + credentials are obtained from the ``/etc/openstack/clouds.yaml`` file + thanks to ``--os-cloud`` argument. diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst index 1cb16ad0..89160a13 100644 --- a/doc/source/user/usage.rst +++ b/doc/source/user/usage.rst @@ -25,7 +25,7 @@ Examples of usage with sourced credentials step **as a prerequisite**: * Source your OpenStack RC file containing the cloud credentials. Let's say - you have a overcloud_rc file with the following content: + you have an overcloud_rc file with the following content: .. code-block:: shell-session @@ -204,9 +204,9 @@ The generated tempest.conf will look like: non-admin argument ++++++++++++++++++ -If your credentials are **non-admin ones**, which means, you are -**not allowed** to create any resources in your cloud, please, specify -``--non-admin`` argument. When the argument is used, ``python-tempestconf`` +If your credentials are **non-admin ones**, which means that you are +**not allowed** to create any resources in your cloud, then please specify +``--non-admin`` argument. When this argument is used, ``python-tempestconf`` will **not create** any resources. .. code-block:: shell-session @@ -248,7 +248,8 @@ the following content: volume_api_version: '2' Then if you use ``--os-cloud`` argument you can run -:command:`discover-tempest-config` **without** sourcing any OpenStack RC file. +:command:`discover-tempest-config` **without** setting any OS_* environment +variable (for example by sourcing any OpenStack RC file). ``--os-cloud`` defines specifies one of the cloud names located in the ``clouds.yaml`` file. @@ -352,7 +353,7 @@ image. Then the image is uploaded to glance again and but --image /my/path/to/myImage.img In the following example, an `override`_ value is used to set -**conpute.image_ref**, which means, that the image specified by ``--image`` is +**compute.image_ref**, which means that the image specified by ``--image`` is uploaded and only **compute.image_alt_ref** is set to the ID of newly created image.