From 8138c3ff9aa9dac1bb8c4ad90f8e158cca1a87d8 Mon Sep 17 00:00:00 2001 From: Omer Date: Thu, 20 Jan 2022 15:42:16 +0100 Subject: [PATCH] Refactor Tobiko installation guide So far the Tobiko docs were duplicated in some places, different (although duplicated), and some fragments were not relevant (or outdated). This patch refactors the Tobiko installation guide by modularizing the fragments ("spilling" fragments instead of coping them), correcting typos, and deleting/updating irrelevant information. Note: in order to see how the change will appear, download it with `git review -d `, run the `tox -e docs` command, and then double click (with the file explorer) tobiko/doc/build/html/. Change-Id: Ib5ce8a166bb036a5c49a396e568f8bd8b79f6a17 --- doc/source/user/_install_venv.rst | 43 +++++++++++++++++++++ doc/source/user/index.rst | 6 +-- doc/source/user/install.rst | 52 +++----------------------- doc/source/user/quick-start.rst | 62 +++---------------------------- 4 files changed, 56 insertions(+), 107 deletions(-) create mode 100644 doc/source/user/_install_venv.rst diff --git a/doc/source/user/_install_venv.rst b/doc/source/user/_install_venv.rst new file mode 100644 index 000000000..26b2cd675 --- /dev/null +++ b/doc/source/user/_install_venv.rst @@ -0,0 +1,43 @@ +Install test cases within a virtualenv +-------------------------------------- + +The safest way to run test cases is to do it within a +`Virtualenv `__. Here we are goint to see how +to setup an environment with all test case dependencies. + +In **RHEL**, **CentOS** or **Fedora** install the following packages:: + + sudo dnf install -y gcc git python3 python3-devel python3-pip which findutils + +In **Debian** or **Ubuntu** install following packages:: + + sudo apt update + sudo apt install -y gcc git python3 python3-dev python3-pip + +Ensure Pip is up-to-date:: + + python3 -m pip install --upgrade --user pip + +Ensure Tox is installed and up-to-date:: + + python3 -m pip install --upgrade --user setuptools virtualenv wheel tox + +Get source code using Git and enter into Tobiko source folder:: + + git clone https://opendev.org/x/tobiko.git + cd tobiko + +Install remaining binary packages:: + + tools/install-bindeps.sh + +Crate the virtual environment with Tox:: + + python3 -m tox -e py3 --notest + +In case you want to activate the virtual environment you can then type:: + + . .tox/py3/bin/activate + +At this point the environment should have all dependencies installed for running test +cases. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index f701079ec..e34da5894 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,8 +1,8 @@ .. _tobiko-user-guide: -================= -Tobiko User Guide -================= +========== +User Guide +========== .. toctree:: :maxdepth: 2 diff --git a/doc/source/user/install.rst b/doc/source/user/install.rst index 6e0a8c9a5..c57aa5c66 100644 --- a/doc/source/user/install.rst +++ b/doc/source/user/install.rst @@ -1,15 +1,11 @@ .. _tobiko-installation-guide: -========================= -Tobiko Installation Guide -========================= +======= +Install +======= +This document describes how to setup an environment for running test cases -Document Overview ------------------ - -This document describes how to install Tobiko inside a -`Python virtualenv `__. .. sidebar:: See also @@ -21,46 +17,8 @@ This document describes how to install Tobiko inside a To run Tobiko scenario test cases please look at :ref:`tobiko-test-case-execution-guide`. -Install Tobiko Using virtualenv -------------------------------- -Make sure gcc, Git and base Python packages are installed on your system. - -For instance on a RHEL7 or CentOS 7 machine you could type:: - - sudo yum install -y gcc git python python-devel wget - -For instance on a RHEL8 or CentOS 8 machine you could type:: - - sudo dnf install -y gcc git python3 python3-devel wget - sudo alternatives --set python /usr/bin/python3 - -Make sure pip is installed and up-to-date:: - - wget https://bootstrap.pypa.io/get-pip.py - sudo python get-pip.py - PIP=$(which pip) - -Make sure setuptools, virtualenv, and wheel are installed and up-to-date:: - - sudo $PIP install --upgrade setuptools virtualenv wheel - -Get Tobiko source code using Git and enter into Tobiko source folder:: - - git clone https://opendev.org/x/tobiko.git - cd tobiko - -To install Tobiko and its dependencies it's safest to create a clean virtualenv -to install it. Create a virtualenv and activate it:: - - virtualenv .tobiko-env - source .tobiko-env/bin/activate - -Install Tobiko and its requirements:: - - pip install \ - -c https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt \ - . +.. include:: _install_venv.rst What's Next diff --git a/doc/source/user/quick-start.rst b/doc/source/user/quick-start.rst index dc544c035..50f4d7fee 100644 --- a/doc/source/user/quick-start.rst +++ b/doc/source/user/quick-start.rst @@ -1,15 +1,10 @@ .. _tobiko-quick-start-guide: -======================== -Tobiko Quick Start Guide -======================== +=========== +Quick Start +=========== - -Document Overview ------------------ - -This document describes how to install execute Tobiko test cases -using `Tox `__. +This document describes how to setup an environment and how to run test cases .. sidebar:: See also @@ -22,54 +17,7 @@ using `Tox `__. :ref:`tobiko-test-case-execution-guide`. -Install Dependencies --------------------- - -Install Basic Python Packages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Make sure Git and Python 3 are installed on your system. - -For instance on RedHat Linux / Fedora:: - - sudo dnf install -y git python3 which - -Check your Python 3 version is 3.6 or greater:: - - python3 --version - -Make sure pip is installed and up-to date:: - - curl https://bootstrap.pypa.io/get-pip.py | sudo python3 - -Check installed Pip version:: - - python3 -m pip --version - -Make sure basic Python packages are installed and up-to-date:: - - sudo python3 -m pip install --upgrade setuptools wheel virtualenv tox six - -Check installed Tox version:: - - tox --version - - -Clone the Tobiko repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Clone the Tobiko repository using Git:: - - git clone https://opendev.org/x/tobiko.git - cd tobiko - - -Install Missing Binary Packages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Install required binary packages:: - - tools/install-bindeps.sh +.. include:: _install_venv.rst Configure Logging Options