openinfra
/
refstack
Code Issues Proposed changes

Fix documentation structure 

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

Change-Id: I4ae3a0274b1f3201a44bbac516c00f16dec5ce55
This commit is contained in:
lpiwowar 2021-10-05 16:33:03 +02:00
parent bb880eced0
commit 83a6715462
12 changed files with 155 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/source/conf.py
View File

@ -56,7 +56,7 @@ version = '1.0'
release = '1.0'
# openstackdocstheme options
repository_name = 'openstack/refstack'
openstackdocs_repo_name = 'osf/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

32
doc/source/index.rst
View File

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

2
doc/source/refstack.rst
View File

@ -1,3 +1,4 @@
===================
RefStack Quickstart
===================
@ -294,3 +295,4 @@ The RefStack documentation can be build using following commands:
``tox -e docs``
The documentation files will be build under ``~/refstack/build/sphinx``.

82
doc/source/run_in_docker.rst → doc/source/run_in_docker/Option1AnsiblePlaybook.rst
View File

@ -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

76
doc/source/run_in_docker/Option2UsingAScript.rst Normal file
View File

@ -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

9
doc/source/run_in_docker/index.rst Normal file
View File

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

5
doc/source/test_result_management.rst
View File

@ -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.

1
doc/source/uploading_private_results.rst
View File

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

36
doc/source/vendor_product_management/ProductEntity.rst Normal file
View File

@ -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.

46
doc/source/vendor_product.rst → doc/source/vendor_product_management/VendorEntity.rst Executable file → Normal file
View File

@ -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.

15
doc/source/vendor_product_management/index.rst Normal file
View File

@ -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

4
tox.ini
View File

@ -1,6 +1,5 @@
[tox]
envlist = py36,py38,pep8,pip-check-reqs
minversion = 3.18
skipsdist = True
[testenv]
@ -49,7 +48,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]