Fix documentation structure

This patch fixes the structure of the Refstack documentation and
tries to make it more readable.

Change-Id: I4ae3a0274b1f3201a44bbac516c00f16dec5ce55

doc/source/conf.py

@@ -56,7 +56,7 @@ version = '1.0'
 release = '1.0'
 
 # openstackdocstheme options
-repository_name = 'openstack/refstack'
+openstackdocs_repo_name = 'openinfra/refstack'
 bug_project = '878'
 bug_tag = ''
 
@@ -103,7 +103,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'openstackdocs'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

doc/source/index.rst

@@ -7,38 +7,16 @@
 Welcome to RefStack's documentation!
 ====================================
 
---------------
+.. include:: README.rst
-About RefStack
---------------
 
-.. toctree::
-   :maxdepth: 2
-
-   README
-
---------------------------
-Installing RefStack Server
---------------------------
 
+Content:
+--------
 .. toctree::
    :maxdepth: 2
 
    refstack
-   run_in_docker
+   run_in_docker/index
-
+   vendor_product_management/index
---------------
-Using RefStack
---------------
-
-.. toctree::
-   :maxdepth: 2
-
    uploading_private_results
-   vendor_product
    test_result_management
-
-------------------
-Indices and tables
-------------------
-
-* :ref:`search`

doc/source/refstack.rst

@@ -1,3 +1,4 @@
+===================
 RefStack Quickstart
 ===================
 
@@ -7,90 +8,86 @@ Ubuntu 14 and 16 LTS.
 
 Install API dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^
+::
 
-``sudo apt-get install git python-dev python-virtualenv libssl-dev build-essential libffi-dev``
+   sudo apt-get install git python-dev python-virtualenv libssl-dev build-essential libffi-dev
-
+   sudo apt-get install mysql-server python-mysqldb
-``sudo apt-get install mysql-server python-mysqldb``
 
 Install RefStack UI dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-``curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -``
+::
 
-``curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -``
+   curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
-
+   curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
-``echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list``
+   echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
-
+   sudo apt-get update && sudo apt-get install -y nodejs yarn
-``sudo apt-get update && sudo apt-get install -y nodejs yarn``
 
 Setup the RefStack database
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-**Log into MySQL:**
+**Log into MySQL**::
 
-``mysql -u root -p``
+   mysql -u root -p
 
-**After authentication, create the database:**
+**After authentication, create the database**::
 
-``CREATE DATABASE refstack;``
+   CREATE DATABASE refstack;
 
-**Create a refstack user:**
+**Create a refstack user**::
 
-``CREATE USER 'refstack'@'localhost' IDENTIFIED BY '<your password>';``
+   CREATE USER 'refstack'@'localhost' IDENTIFIED BY '<your password>';
 
-or using hash value for your password
+**or using hash value for your password**::
 
-``CREATE USER 'refstack'@'localhost'    IDENTIFIED BY PASSWORD '<hash value of your password';``
+   CREATE USER 'refstack'@'localhost' IDENTIFIED BY PASSWORD '<hash value of your password';
 
-**Grant privileges:**
+**Grant privileges**::
 
-``GRANT ALL PRIVILEGES ON refstack . * TO 'refstack'@'localhost';``
+   GRANT ALL PRIVILEGES ON refstack . * TO 'refstack'@'localhost';
 
-**Reload privileges:**
+**Reload privileges**::
 
-``FLUSH PRIVILEGES;``
+   FLUSH PRIVILEGES;
 
-**Exit MySQL:**
+**Exit MySQL**::
 
-``quit``
+   quit
 
 Clone the repository
 ^^^^^^^^^^^^^^^^^^^^
+::
 
-``git clone https://opendev.org/osf/refstack``
+   git clone https://opendev.org/osf/refstack
+   cd refstack
 
-``cd refstack``
+**Create virtual environment**::
 
-**Create virtual environment:**
+   virtualenv .venv --system-site-package
 
-``virtualenv .venv --system-site-package``
+**Source to virtual environment**::
 
-**Source to virtual environment:**
+   source .venv/bin/activate
 
-``source .venv/bin/activate``
+**Update pip**::
 
-**Update pip**
+   pip install -U pip
 
-``pip install -U pip``
+**Install environment pre-requirements**::
 
-**Install environment pre-requirements**
+   pip install gunicorn==18 # App server
-
+   pip install PyMySQL>=0.6.2,!=0.6.4 # python mysql connector
-# App server
-
-``pip install gunicorn==18``
-
-# python mysql connector
-
-``pip install PyMySQL>=0.6.2,!=0.6.4``
 
 Install RefStack application
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
 
-``pip install .``
+   pip install .
 
 Install needed RefStack UI library dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
 
-``yarn``
+   yarn
 
 API configuration file preparation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -136,9 +133,9 @@ Create UI config file
 
 From the RefStack project root directory, create a config.json file and
 specify your API endpoint inside this file. This will be something like
-{"refstackApiUrl": "http://192.168.56.101:8000/v1"}:
+{"refstackApiUrl": "http://192.168.56.101:8000/v1"}::
 
-``cp refstack-ui/app/config.json.sample refstack-ui/app/config.json``
+   cp refstack-ui/app/config.json.sample refstack-ui/app/config.json
 
 Openstack OpenID endpoint configuration (optional)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -188,21 +185,21 @@ the ``[osid]`` section in refstack.conf to match the local endpoint.
 Database sync
 ^^^^^^^^^^^^^
 
-**Check current revision:**
+**Check current revision**::
 
-``refstack-manage --config-file /path/to/refstack.conf version``
+   refstack-manage --config-file /path/to/refstack.conf version
 
 The response will show the current database revision. If the revision is
 ``None`` (indicating a clear database), the following command should be
 performed to upgrade the database to the latest revision:
 
-**Upgrade database to latest revision:**
+**Upgrade database to latest revision**::
 
-``refstack-manage --config-file /path/to/refstack.conf upgrade --revision head``
+   refstack-manage --config-file /path/to/refstack.conf upgrade --revision head
 
-**Check current revision:**
+**Check current revision**::
 
-``refstack-manage --config-file /path/to/refstack.conf version``
+   refstack-manage --config-file /path/to/refstack.conf version
 
 ::
 
@@ -215,7 +212,9 @@ The RefStack About page is populated with HTML templates generated from
 our RST documentation files. If you want this information displayed, then
 run the following command from the root of the project.
 
-``./tools/convert-docs.py -o ./refstack-ui/app/components/about/templates ./doc/source/*.rst``
+::
+
+   ./tools/convert-docs.py -o ./refstack-ui/app/components/about/templates ./doc/source/*.rst
 
 Ignore any unknown directive errors.
 
@@ -223,9 +222,9 @@ Start RefStack
 ^^^^^^^^^^^^^^
 
 A simple way to start refstack is to just kick off gunicorn using the
-``refstack-api`` executable:
+``refstack-api`` executable::
 
-``refstack-api --env REFSTACK_OSLO_CONFIG=/path/to/refstack.conf``
+   refstack-api --env REFSTACK_OSLO_CONFIG=/path/to/refstack.conf
 
 If ``app_dev_mode`` is set to true, this will launch both the UI and
 API.
@@ -255,42 +254,41 @@ Overall RefStack admin access is given to users belonging to a
 logged into RefStack at least once so that a user record for your
 account is created.
 
-**Log into MySQL:**
+**Log into MySQL**::
 
-``mysql -u root -p``
+   mysql -u root -p
 
-**Create a group for the "Foundation" organization:**
+**Create a group for the "Foundation" organization**::
 
-``INSERT INTO refstack.group (id, name, created_at) VALUES (UUID(), 'Foundation Group', NOW());``
+   INSERT INTO refstack.group (id, name, created_at) VALUES (UUID(), 'Foundation Group', NOW());
 
-**Get the group ID for the group you just created:**
+**Get the group ID for the group you just created**::
 
-``SELECT id from refstack.group WHERE name = 'Foundation Group';``
+   SELECT id from refstack.group WHERE name = 'Foundation Group';
 
-**Get your OpenID:**
+**Get your OpenID**::
 
-``SELECT openid from refstack.user WHERE email = '<your email>';``
+   SELECT openid from refstack.user WHERE email = '<your email>';
 
 **Add your user account to the previously created "Foundation" group.**
 
 Replace ``<Group ID>`` and ``<Your OpenID>`` with the values
-retrieved in the two previous steps:
+retrieved in the two previous steps::
 
-``INSERT INTO refstack.user_to_group (created_by_user, user_openid, group_id, created_at)    VALUES ('<Your OpenID>', '<Your OpenID>', '<Group ID>', NOW());``
+   INSERT INTO refstack.user_to_group (created_by_user, user_openid, group_id, created_at)    VALUES ('<Your OpenID>', '<Your OpenID>', '<Group ID>', NOW());
 
-**Create the actual "Foundation" organization using this group:**
+**Create the actual "Foundation" organization using this group**::
 
-``INSERT INTO refstack.organization (id, type, name, group_id, created_by_user, created_at)    VALUES (UUID(), 0, 'Foundation', '<Group ID>', '<Your OpenID>', NOW());``
+   INSERT INTO refstack.organization (id, type, name, group_id, created_by_user, created_at)    VALUES (UUID(), 0, 'Foundation', '<Group ID>', '<Your OpenID>', NOW());
 
 (Optional) Build documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The RefStack documentation can be build using following commands:
+The RefStack documentation can be build using following commands::
 
-``cd ~/refstack; source .venv/bin/activate``
+   cd ~/refstack; source .venv/bin/activate
-
+   sudo apt-get install python3-dev python-tox
-``sudo apt-get install python3-dev python-tox``
+   tox -e docs
-
-``tox -e docs``
 
 The documentation files will be build under ``~/refstack/build/sphinx``.
+

doc/source/run_in_docker/Option1AnsiblePlaybook.rst

@@ -1,8 +1,6 @@
-Run-in-docker manual
+====================================
-====================
-
 Option 1 - Using an ansible playbook
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+====================================
 These steps are meant for RefStack developers to help them with setting up
 a local refstack instance.
 
@@ -31,7 +29,6 @@ and then restart the apache service so that it loads the new configuration::
 
     $ systemctl restart apache2
 
-
 How to edit refstack files within the container
 -----------------------------------------------
 
@@ -100,78 +97,3 @@ To see the server's logs use the following command::
 
     $ docker container logs -f <container name>
 
-
-Option 2 - Using a script
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-NOTE: This is currently outdated, follow the Option 1 for now.
-
-The main purpose of the ``run-in-docker`` script is to provide a
-convenient way to create a local setup of RefStack inside a Docker
-container. It should be helpful for new developers and also for testing
-new features.
-
-Requirements:
-^^^^^^^^^^^^^
-
--  ``Docker >= 1.6`` (How to update on
-   `Ubuntu <http://www.ubuntuupdates.org/ppa/docker>`__)
-
-How to use:
-^^^^^^^^^^^
-
-Just run the ``run-in-docker`` script, but is important to first set
-env[REFSTACK\_HOST] with the public host/IP for your local API. If you
-want to test RefStack with OpenStackid you should point a valid local
-alias here. For example:
-
-``export REFSTACK_HOST=myrefstack.com``
-
-By default 127.0.0.1 is used.
-
-After it completes, check that the site is running on https://127.0.0.1.
-
-The script will build a RefStack docker image with all dependencies, and
-will run a container from this image. By default, RefStack will run
-inside this container. You also can run ``run-in-docker bash`` to get
-access into the container. If you stop the RefStack server by pressing
-'Ctrl-C', the container is kept alive and will be re-used next time.
-
-You can customize the RefStack API config by editing
-``docker/templates/refstack.conf.tmpl``. It is a bash template, so you
-can use ${SOME\_ENV\_VARIABLE} in it.
-
-This script can make the reviewing process much easier because it
-creates separate containers for each review. Containers get names in the
-form refstack\_{REVIEW-TOPIC}. Database schema changes are automatically
-handled, too, where the script creates a data container for each
-database revision (refstack\_data\_{DATA-BASE-REVISON}) and reuses it
-where possible. For example, if a new review uses an existing database
-revision, that database container will be used.
-
-Available script options:
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
--  ``-r`` Force delete the RefStack container and run it again. This
-   will update the RefStack config from template noted above.
--  ``-i`` Run a container with isolated MySQL data. By default MySQL
-   data is stored in a refstack\_data\_{DATA-BASE-REVISON} container. It
-   reuses this container if such one exists. If you want to drop the DB
-   data, just execute
-   ``sudo docker rm refstack_data_{DATA-BASE-REVISON}``.
--  ``-b`` Force delete RefStack image and build it again. This rebuilds
-   the Python and JS environment for RefStack.
--  ``-d`` Turn on debug information.
--  ``-h`` Print usage message.
-
-Useful in-container commands/aliases:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
--  ``api-up`` - sync project and run the RefStack API
--  ``api-init-db`` - initialize the RefStack database
--  ``api-db-version`` - get current migration version of the RefStack
-   database
--  ``api-sync`` - sync project files in the container with the project
-   files on the host
--  ``activate`` - activate the python virtual env
--  ``mysql`` - open the MySQL console

doc/source/run_in_docker/Option2UsingAScript.rst

@@ -0,0 +1,76 @@
+=========================
+Option 2 - Using a script
+=========================
+
+NOTE: This is currently outdated, follow the Option 1 for now.
+
+The main purpose of the ``run-in-docker`` script is to provide a
+convenient way to create a local setup of RefStack inside a Docker
+container. It should be helpful for new developers and also for testing
+new features.
+
+Requirements:
+-------------
+
+-  ``Docker >= 1.6`` (How to update on
+   `Ubuntu <http://www.ubuntuupdates.org/ppa/docker>`__)
+
+How to use:
+-----------
+
+Just run the ``run-in-docker`` script, but is important to first set
+env[REFSTACK\_HOST] with the public host/IP for your local API. If you
+want to test RefStack with OpenStackid you should point a valid local
+alias here. For example:
+
+``export REFSTACK_HOST=myrefstack.com``
+
+By default 127.0.0.1 is used.
+
+After it completes, check that the site is running on https://127.0.0.1.
+
+The script will build a RefStack docker image with all dependencies, and
+will run a container from this image. By default, RefStack will run
+inside this container. You also can run ``run-in-docker bash`` to get
+access into the container. If you stop the RefStack server by pressing
+'Ctrl-C', the container is kept alive and will be re-used next time.
+
+You can customize the RefStack API config by editing
+``docker/templates/refstack.conf.tmpl``. It is a bash template, so you
+can use ${SOME\_ENV\_VARIABLE} in it.
+
+This script can make the reviewing process much easier because it
+creates separate containers for each review. Containers get names in the
+form refstack\_{REVIEW-TOPIC}. Database schema changes are automatically
+handled, too, where the script creates a data container for each
+database revision (refstack\_data\_{DATA-BASE-REVISON}) and reuses it
+where possible. For example, if a new review uses an existing database
+revision, that database container will be used.
+
+Available script options:
+-------------------------
+
+-  ``-r`` Force delete the RefStack container and run it again. This
+   will update the RefStack config from template noted above.
+-  ``-i`` Run a container with isolated MySQL data. By default MySQL
+   data is stored in a refstack\_data\_{DATA-BASE-REVISON} container. It
+   reuses this container if such one exists. If you want to drop the DB
+   data, just execute
+   ``sudo docker rm refstack_data_{DATA-BASE-REVISON}``.
+-  ``-b`` Force delete RefStack image and build it again. This rebuilds
+   the Python and JS environment for RefStack.
+-  ``-d`` Turn on debug information.
+-  ``-h`` Print usage message.
+
+Useful in-container commands/aliases:
+-------------------------------------
+
+-  ``api-up`` - sync project and run the RefStack API
+-  ``api-init-db`` - initialize the RefStack database
+-  ``api-db-version`` - get current migration version of the RefStack
+   database
+-  ``api-sync`` - sync project files in the container with the project
+   files on the host
+-  ``activate`` - activate the python virtual env
+-  ``mysql`` - open the MySQL console
+

doc/source/run_in_docker/index.rst

@@ -0,0 +1,9 @@
+Run-in-docker manual
+====================
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   Option1AnsiblePlaybook
+   Option2UsingAScript

doc/source/test_result_management.rst

@@ -1,8 +1,9 @@
+======================
 Test result management
 ======================
 
 Test result to product version association
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------------------
 
 Test results uploaded by users can be associated to a version of a product. To
 perform this association, the user must be both the one who uploaded the result
@@ -11,7 +12,7 @@ associated to a product, all admins of the vendor which owns the product can
 manage the test result.
 
 Mark or unmark a test results as verified
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------------------
 
 Only Foundation admins can mark and un-mark a test as verified.  A verified
 test result can not be updated or deleted.

doc/source/uploading_private_results.rst

@@ -1,3 +1,4 @@
+======================================
 How to upload test results to RefStack
 ======================================
 

doc/source/vendor_product_management/ProductEntity.rst

@@ -0,0 +1,36 @@
+==============
+Product entity
+==============
+
+Any user who has successfully authenticated to the RefStack server can create
+product entities. The minimum information needed to create a product entity is
+as follows:
+
+- Name
+
+  This is the name of the product entity being created.
+
+- Product type:
+
+  Product types are defined by OpenStack as shown on the OpenStack Marketplace
+  ( https://www.openstack.org/marketplace/ ). Currently, there are three types
+  of products, namely: Distro & Appliances, Hosted Private Clouds and Public
+  Clouds.
+
+- Vendor
+
+  This is the vendor which owns the product. A default vendor will be created
+  for the user if no vendor entity exists for this user.
+
+Whenever a product is created, by default, it is a private product and is only
+visible to its vendor users. Vendor users can make a product publicly visible
+as needed later. However, only products that are owned by official vendors can
+be made publicly visible.
+
+Product version
+~~~~~~~~~~~~~~~
+
+A default version is created whenever a product is created. The name of the
+default version is blank. The default version is used for products that have
+no version. Users can add new product versions to the product as needed.
+

doc/source/vendor_product_management/VendorEntity.rst

@@ -1,14 +1,6 @@
-Vendor and product management
+=============
-=============================
-
-RefStack has implemented a vendor and product registration process so that test
-results can be associated to products of vendors. The creation and management
-of vendor and product entities can be done using the RefStack Server UI or
-RefStack APIs. The following is a quick guide outlining the information related
-to the creation and management of those entities.
-
 Vendor entity
-^^^^^^^^^^^^^
+=============
 
 Any user who has successfully authenticated to the RefStack server can create
 vendor entities. The minimum required information to create a vendor is the
@@ -55,37 +47,3 @@ There are four types of vendor entities in RefStack:
   type will be changed from "pending" to "official". Official vendors are
   visible to all RefStack users.
 
-Product entity
-^^^^^^^^^^^^^^
-
-Any user who has successfully authenticated to the RefStack server can create
-product entities. The minimum information needed to create a product entity is
-as follows:
-
-- Name
-
-  This is the name of the product entity being created.
-
-- Product type:
-
-  Product types are defined by OpenStack as shown on the OpenStack Marketplace
-  ( https://www.openstack.org/marketplace/ ). Currently, there are three types
-  of products, namely: Distro & Appliances, Hosted Private Clouds and Public
-  Clouds.
-
-- Vendor
-
-  This is the vendor which owns the product. A default vendor will be created
-  for the user if no vendor entity exists for this user.
-
-Whenever a product is created, by default, it is a private product and is only
-visible to its vendor users. Vendor users can make a product publicly visible
-as needed later. However, only products that are owned by official vendors can
-be made publicly visible.
-
-Product version
-~~~~~~~~~~~~~~~
-
-A default version is created whenever a product is created. The name of the
-default version is blank. The default version is used for products that have
-no version. Users can add new product versions to the product as needed.

doc/source/vendor_product_management/index.rst

@@ -0,0 +1,15 @@
+Vendor and product management
+=============================
+
+RefStack has implemented a vendor and product registration process so that test
+results can be associated to products of vendors. The creation and management
+of vendor and product entities can be done using the RefStack Server UI or
+RefStack APIs. The following is a quick guide outlining the information related
+to the creation and management of those entities.
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   VendorEntity
+   ProductEntity

tox.ini

@@ -49,7 +49,8 @@ commands = {posargs}
 commands = {toxinidir}/tools/cover.sh {posargs}
 
 [testenv:docs]
-deps = -r{toxinidir}/doc/requirements.txt
+deps = -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
+       -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -b html doc/source doc/build/html
 
 [flake8]