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
f6a781374b
commit
226ad4c126
|
@ -30,6 +30,9 @@ import os
|
|||
# ones.
|
||||
extensions = ['openstackdocstheme']
|
||||
|
||||
# openstackdocstheme options
|
||||
openstackdocs_repo_name = 'osf/refstack'
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
#templates_path = ['_templates']
|
||||
|
||||
|
@ -103,7 +106,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
|
||||
|
|
|
@ -1,3 +1,4 @@
|
|||
======================================
|
||||
How to upload test results to RefStack
|
||||
======================================
|
||||
|
|
@ -7,38 +7,17 @@
|
|||
Welcome to RefStack's documentation!
|
||||
====================================
|
||||
|
||||
--------------
|
||||
About RefStack
|
||||
--------------
|
||||
.. include:: README.rst
|
||||
|
||||
|
||||
Content:
|
||||
--------
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:titlesonly:
|
||||
|
||||
README
|
||||
|
||||
--------------------------
|
||||
Installing RefStack Server
|
||||
--------------------------
|
||||
|
||||
.. 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`
|
||||
refstack_quickstart/index
|
||||
run_in_docker/index
|
||||
vendor_product_management/index
|
||||
how_to_upload_test_results/index
|
||||
test_result_management/index
|
||||
|
|
|
@ -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``.
|
||||
|
|
@ -1,6 +1,3 @@
|
|||
Run-in-docker manual
|
||||
====================
|
||||
|
||||
Option 1 - Using an ansible playbook
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
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
|
||||
|
||||
|
||||
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>
|
||||
|
||||
|
||||
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 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.
|
|
@ -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
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
|
@ -55,37 +46,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.
|
|
@ -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}
|
||||
|
||||
[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]
|
||||
|
|
Loading…
Reference in New Issue