From 40a5a9707570a19eab8f9ce171633cd49234ad2d Mon Sep 17 00:00:00 2001 From: Martin Kopec Date: Wed, 4 Jul 2018 14:20:40 +0000 Subject: [PATCH] Fix documentation structure Usage section is there twice, it's because the README.rst is included in doc too and it contains usage section as well. The patch fixes that by not including the README.rst and copies the content of README.rst to the documentation, in order to have at least some, while documentation is being written or reviewed. Change-Id: I0247289029cd63b354965242ce7c1eca65f945eb Story: 2002703 Task: 22543 --- doc/source/{ => contributor}/contributing.rst | 0 doc/source/contributor/index.rst | 8 ++ doc/source/index.rst | 12 ++- doc/source/install/index.rst | 8 ++ doc/source/{ => install}/installation.rst | 0 doc/source/overview.rst | 14 +++ doc/source/readme.rst | 1 - doc/source/usage.rst | 7 -- doc/source/user/index.rst | 8 ++ doc/source/user/usage.rst | 99 +++++++++++++++++++ 10 files changed, 144 insertions(+), 13 deletions(-) rename doc/source/{ => contributor}/contributing.rst (100%) create mode 100644 doc/source/contributor/index.rst create mode 100644 doc/source/install/index.rst rename doc/source/{ => install}/installation.rst (100%) create mode 100644 doc/source/overview.rst delete mode 100644 doc/source/readme.rst delete mode 100644 doc/source/usage.rst create mode 100644 doc/source/user/index.rst create mode 100644 doc/source/user/usage.rst diff --git a/doc/source/contributing.rst b/doc/source/contributor/contributing.rst similarity index 100% rename from doc/source/contributing.rst rename to doc/source/contributor/contributing.rst 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 dea00566..756f1f6b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,20 +6,22 @@ Welcome to python-tempestconf's documentation! ======================================================== +python-tempestconf is a tool for automatic generation of tempest configuration +based on user's cloud. + Contents: .. toctree:: :maxdepth: 2 - readme - installation - usage - contributing + overview + install/index + user/index + contributor/index Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 00000000..3dc47361 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,8 @@ +Install Guide +============= + +.. toctree:: + :maxdepth: 2 + :includehidden: + + installation diff --git a/doc/source/installation.rst b/doc/source/install/installation.rst similarity index 100% rename from doc/source/installation.rst rename to doc/source/install/installation.rst diff --git a/doc/source/overview.rst b/doc/source/overview.rst new file mode 100644 index 00000000..0cc905a7 --- /dev/null +++ b/doc/source/overview.rst @@ -0,0 +1,14 @@ +======== +Overview +======== + +python-tempestconf will automatically generate the tempest configuration +based on your cloud. + +- Free software: Apache license +- Documentation: + http://git.openstack.org/cgit/openstack/python-tempestconf/tree/README.rst +- Source: https://git.openstack.org/openstack/python-tempestconf +- Bugs: https://storyboard.openstack.org/#!/project/912 +- Release notes: https://docs.openstack.org/releasenotes/python-tempestconf + diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3d..00000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index 79675e1b..00000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Usage -======== - -To use python-tempestconf in a project:: - - import tempest_config diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 00000000..03dde542 --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,8 @@ +Usage +===== + +.. toctree:: + :maxdepth: 2 + :includehidden: + + usage diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst new file mode 100644 index 00000000..788abd6f --- /dev/null +++ b/doc/source/user/usage.rst @@ -0,0 +1,99 @@ +======== +Usage +======== + +To use python-tempestconf in a project:: + + import tempest_config + +Git +--- + +1. Clone and change to the directory: + +.. code-block:: shell-session + + $ git clone https://git.openstack.org/openstack/python-tempestconf + $ cd python-tempestconf + +2. Create virtual environment using virtualenv: + +.. code-block:: shell-session + + $ virtualenv .venv + $ source .venv/bin/activate + +3. Source the newly created virtual environment and install + requirements: + +.. code-block:: shell-session + + (.venv) $ pip install -r requirements.txt + (.venv) $ pip install -r test-requirements.txt + +4. Source cloud credentials, for example: + +.. code-block:: shell-session + + (py27) $ source cloudrc + +5. Run python-tempestconf to generate tempest configuration file: + +.. code-block:: shell-session + + (py27) $ python config_tempest/config_tempest.py --debug identity.uri $OS_AUTH_URL \ + identity.admin_password $OS_PASSWORD --create + +After this, ``./etc/tempest.conf`` is generated. + +RPM Installation (RDO) +---------------------- + +1. python-tempestconf is installed together with openstack-tempest, as + a new dependency (starting from the Ocata release) + +.. code-block:: shell-session + + # yum install openstack-tempest + +2. Source cloud credentials, initialize tempest and run the discovery + tool: + +.. code-block:: shell-session + + $ source cloudrc + $ tempest init testingdir + $ cd testingdir + $ discover-tempest-config --debug identity.uri $OS_AUTH_URL \ + identity.admin_password $OS_PASSWORD --create + +.. note:: + In Ocata release new features were presented. + ``discover-tempest-config`` is the new name of the **old** + ``config_tempest.py`` script and it **accepts the same parameters.** + More about new features can be found + `here `__ + + +os-client-config support +------------------------ + +python-tempestconf supports `os-client-config `__ +so instead of sourcing openstackrc files you can use clouds.yml files. Location where +these files should be stored and syntax which is used to specify cloud.yaml files +can be found `here `__ + +In case of git usage: + +.. code-block:: shell-session + + (py27) $ python config_tempest/config_tempest.py --debug --create --os-cloud + +In case of RPM: + +.. code-block:: shell-session + + $ tempest init testingdir + $ cd testingdir + $ discover-tempest-config --debug --create --os-cloud +