From 226ad4c1265f4978d373a340e784d312468f17d7 Mon Sep 17 00:00:00 2001 From: lpiwowar Date: Tue, 5 Oct 2021 16:33:03 +0200 Subject: [PATCH] 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 | 5 +- .../index.rst} | 1 + doc/source/index.rst | 41 +++------- .../index.rst} | 2 + .../Option1AnsiblePlaybook.rst} | 79 ------------------- .../run_in_docker/Option2UsingAScript.rst | 75 ++++++++++++++++++ doc/source/run_in_docker/index.rst | 10 +++ .../index.rst} | 5 +- .../ProductEntity.rst | 35 ++++++++ .../VendorEntity.rst} | 43 ---------- .../vendor_product_management/index.rst | 16 ++++ tox.ini | 3 +- 12 files changed, 158 insertions(+), 157 deletions(-) rename doc/source/{uploading_private_results.rst => how_to_upload_test_results/index.rst} (99%) rename doc/source/{refstack.rst => refstack_quickstart/index.rst} (99%) rename doc/source/{run_in_docker.rst => run_in_docker/Option1AnsiblePlaybook.rst} (52%) create mode 100644 doc/source/run_in_docker/Option2UsingAScript.rst create mode 100644 doc/source/run_in_docker/index.rst rename doc/source/{test_result_management.rst => test_result_management/index.rst} (84%) create mode 100644 doc/source/vendor_product_management/ProductEntity.rst rename doc/source/{vendor_product.rst => vendor_product_management/VendorEntity.rst} (51%) mode change 100755 => 100644 create mode 100644 doc/source/vendor_product_management/index.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index e847034b..9e04a89a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 diff --git a/doc/source/uploading_private_results.rst b/doc/source/how_to_upload_test_results/index.rst similarity index 99% rename from doc/source/uploading_private_results.rst rename to doc/source/how_to_upload_test_results/index.rst index 5ad6fa59..cf336fb6 100644 --- a/doc/source/uploading_private_results.rst +++ b/doc/source/how_to_upload_test_results/index.rst @@ -1,3 +1,4 @@ +====================================== How to upload test results to RefStack ====================================== diff --git a/doc/source/index.rst b/doc/source/index.rst index 32ce225d..4aa28d25 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/refstack.rst b/doc/source/refstack_quickstart/index.rst similarity index 99% rename from doc/source/refstack.rst rename to doc/source/refstack_quickstart/index.rst index a282a15d..bd5154d3 100644 --- a/doc/source/refstack.rst +++ b/doc/source/refstack_quickstart/index.rst @@ -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``. + diff --git a/doc/source/run_in_docker.rst b/doc/source/run_in_docker/Option1AnsiblePlaybook.rst similarity index 52% rename from doc/source/run_in_docker.rst rename to doc/source/run_in_docker/Option1AnsiblePlaybook.rst index b57ac748..729a5ac1 100644 --- a/doc/source/run_in_docker.rst +++ b/doc/source/run_in_docker/Option1AnsiblePlaybook.rst @@ -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 - -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 `__) - -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 diff --git a/doc/source/run_in_docker/Option2UsingAScript.rst b/doc/source/run_in_docker/Option2UsingAScript.rst new file mode 100644 index 00000000..c1f91334 --- /dev/null +++ b/doc/source/run_in_docker/Option2UsingAScript.rst @@ -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 `__) + +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 + diff --git a/doc/source/run_in_docker/index.rst b/doc/source/run_in_docker/index.rst new file mode 100644 index 00000000..40f4f120 --- /dev/null +++ b/doc/source/run_in_docker/index.rst @@ -0,0 +1,10 @@ +==================== +Run-in-docker manual +==================== + +.. toctree:: + :maxdepth: 1 + :includehidden: + + Option1AnsiblePlaybook + Option2UsingAScript diff --git a/doc/source/test_result_management.rst b/doc/source/test_result_management/index.rst similarity index 84% rename from doc/source/test_result_management.rst rename to doc/source/test_result_management/index.rst index d11b0a7a..be40c8c4 100755 --- a/doc/source/test_result_management.rst +++ b/doc/source/test_result_management/index.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. diff --git a/doc/source/vendor_product_management/ProductEntity.rst b/doc/source/vendor_product_management/ProductEntity.rst new file mode 100644 index 00000000..83c5d645 --- /dev/null +++ b/doc/source/vendor_product_management/ProductEntity.rst @@ -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. + diff --git a/doc/source/vendor_product.rst b/doc/source/vendor_product_management/VendorEntity.rst old mode 100755 new mode 100644 similarity index 51% rename from doc/source/vendor_product.rst rename to doc/source/vendor_product_management/VendorEntity.rst index 2ba919b3..67178a04 --- a/doc/source/vendor_product.rst +++ b/doc/source/vendor_product_management/VendorEntity.rst @@ -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. diff --git a/doc/source/vendor_product_management/index.rst b/doc/source/vendor_product_management/index.rst new file mode 100644 index 00000000..7866c3a8 --- /dev/null +++ b/doc/source/vendor_product_management/index.rst @@ -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 diff --git a/tox.ini b/tox.ini index 0dfcd257..d623dc21 100644 --- a/tox.ini +++ b/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]