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:
parent
bb880eced0
commit
7a6d1c5e68
|
@ -30,6 +30,9 @@ import os
|
||||||
# ones.
|
# ones.
|
||||||
extensions = ['openstackdocstheme']
|
extensions = ['openstackdocstheme']
|
||||||
|
|
||||||
|
# openstackdocstheme options
|
||||||
|
openstackdocs_repo_name = 'osf/refstack'
|
||||||
|
|
||||||
# Add any paths that contain templates here, relative to this directory.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
#templates_path = ['_templates']
|
#templates_path = ['_templates']
|
||||||
|
|
||||||
|
@ -103,7 +106,7 @@ pygments_style = 'sphinx'
|
||||||
|
|
||||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
# a list of builtin themes.
|
# 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
|
# 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
|
# further. For a list of options available for each theme, see the
|
||||||
|
|
|
@ -1,3 +1,4 @@
|
||||||
|
======================================
|
||||||
How to upload test results to RefStack
|
How to upload test results to RefStack
|
||||||
======================================
|
======================================
|
||||||
|
|
|
@ -7,38 +7,17 @@
|
||||||
Welcome to RefStack's documentation!
|
Welcome to RefStack's documentation!
|
||||||
====================================
|
====================================
|
||||||
|
|
||||||
--------------
|
.. include:: README.rst
|
||||||
About RefStack
|
|
||||||
--------------
|
|
||||||
|
|
||||||
|
|
||||||
|
Content:
|
||||||
|
--------
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
:titlesonly:
|
||||||
|
|
||||||
README
|
refstack_quickstart/index
|
||||||
|
run_in_docker/index
|
||||||
--------------------------
|
vendor_product_management/index
|
||||||
Installing RefStack Server
|
how_to_upload_test_results/index
|
||||||
--------------------------
|
test_result_management/index
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
|
||||||
|
|
||||||
refstack
|
|
||||||
run_in_docker
|
|
||||||
|
|
||||||
--------------
|
|
||||||
Using RefStack
|
|
||||||
--------------
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
|
||||||
|
|
||||||
uploading_private_results
|
|
||||||
vendor_product
|
|
||||||
test_result_management
|
|
||||||
|
|
||||||
------------------
|
|
||||||
Indices and tables
|
|
||||||
------------------
|
|
||||||
|
|
||||||
* :ref:`search`
|
|
||||||
|
|
|
@ -1,3 +1,4 @@
|
||||||
|
===================
|
||||||
RefStack Quickstart
|
RefStack Quickstart
|
||||||
===================
|
===================
|
||||||
|
|
||||||
|
@ -294,3 +295,4 @@ The RefStack documentation can be build using following commands:
|
||||||
``tox -e docs``
|
``tox -e docs``
|
||||||
|
|
||||||
The documentation files will be build under ``~/refstack/build/sphinx``.
|
The documentation files will be build under ``~/refstack/build/sphinx``.
|
||||||
|
|
|
@ -1,6 +1,3 @@
|
||||||
Run-in-docker manual
|
|
||||||
====================
|
|
||||||
|
|
||||||
Option 1 - Using an ansible playbook
|
Option 1 - Using an ansible playbook
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
These steps are meant for RefStack developers to help them with setting up
|
These steps are meant for RefStack developers to help them with setting up
|
||||||
|
@ -31,7 +28,6 @@ and then restart the apache service so that it loads the new configuration::
|
||||||
|
|
||||||
$ systemctl restart apache2
|
$ systemctl restart apache2
|
||||||
|
|
||||||
|
|
||||||
How to edit refstack files within the container
|
How to edit refstack files within the container
|
||||||
-----------------------------------------------
|
-----------------------------------------------
|
||||||
|
|
||||||
|
@ -100,78 +96,3 @@ To see the server's logs use the following command::
|
||||||
|
|
||||||
$ docker container logs -f <container name>
|
$ 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
|
|
|
@ -0,0 +1,75 @@
|
||||||
|
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
|
||||||
|
|
|
@ -0,0 +1,10 @@
|
||||||
|
====================
|
||||||
|
Run-in-docker manual
|
||||||
|
====================
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
:includehidden:
|
||||||
|
|
||||||
|
Option1AnsiblePlaybook
|
||||||
|
Option2UsingAScript
|
|
@ -1,8 +1,9 @@
|
||||||
|
======================
|
||||||
Test result management
|
Test result management
|
||||||
======================
|
======================
|
||||||
|
|
||||||
Test result to product version association
|
Test result to product version association
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
------------------------------------------
|
||||||
|
|
||||||
Test results uploaded by users can be associated to a version of a product. To
|
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
|
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.
|
manage the test result.
|
||||||
|
|
||||||
Mark or unmark a test results as verified
|
Mark or unmark a test results as verified
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
-----------------------------------------
|
||||||
|
|
||||||
Only Foundation admins can mark and un-mark a test as verified. A verified
|
Only Foundation admins can mark and un-mark a test as verified. A verified
|
||||||
test result can not be updated or deleted.
|
test result can not be updated or deleted.
|
|
@ -0,0 +1,35 @@
|
||||||
|
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.
|
||||||
|
|
43
doc/source/vendor_product.rst → doc/source/vendor_product_management/VendorEntity.rst
Executable file → Normal file
43
doc/source/vendor_product.rst → doc/source/vendor_product_management/VendorEntity.rst
Executable file → Normal file
|
@ -1,12 +1,3 @@
|
||||||
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
|
Vendor entity
|
||||||
^^^^^^^^^^^^^
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
@ -55,37 +46,3 @@ There are four types of vendor entities in RefStack:
|
||||||
type will be changed from "pending" to "official". Official vendors are
|
type will be changed from "pending" to "official". Official vendors are
|
||||||
visible to all RefStack users.
|
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.
|
|
|
@ -0,0 +1,16 @@
|
||||||
|
=============================
|
||||||
|
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
|
3
tox.ini
3
tox.ini
|
@ -49,7 +49,8 @@ commands = {posargs}
|
||||||
commands = {toxinidir}/tools/cover.sh {posargs}
|
commands = {toxinidir}/tools/cover.sh {posargs}
|
||||||
|
|
||||||
[testenv:docs]
|
[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
|
commands = sphinx-build -b html doc/source doc/build/html
|
||||||
|
|
||||||
[flake8]
|
[flake8]
|
||||||
|
|
Loading…
Reference in New Issue