Merge pull request #1285 from buildtesters/update_documentation

Redesign buildtest documentation based on divio

docs/builder.rst

@@ -10,12 +10,35 @@ the buildspec will be ignored.
 
 .. image:: _static/GeneralPipeline.png
 
+.. _discover_buildspecs:
+
 Discover Buildspecs
 ---------------------
 
 buildtest will discover buildspecs based on command line arguments since you can
-build by file, directory, executor, or tags.  In **discover** stage, buildtest
-will detect buildspecs which is discussed in :ref:`discover_buildspecs` .
+build by file, directory, executor, or tags.
+
+The buildspec search resolution is described as follows:
+
+- If file or directory specified by ``--buildspec`` option doesn't exist we exit immediately.
+
+- If buildspec path is a directory, traverse directory recursively to find all ``.yml`` extensions
+
+- If buildspec path is a file, check if file extension is not ``.yml``,  exit immediately
+
+- If user specifies ``--tags`` or ``--executor`` we search in buildspec cache to discover buildspecs.
+
+Shown below is a diagram on how buildtest discovers buildspecs. The user can build buildspecs
+by ``--buildspec``, :ref:`--tags <build_by_tags>`, or :ref:`--executor <build_by_executor>`
+which will discover the buildspecs. You can :ref:`exclude buildspecs <exclude_buildspecs>`
+using ``--exclude`` option which is processed after discovering buildspecs. The
+excluded buildspecs are removed from list if found and final list of buildspecs
+is processed.
+
+.. image:: _static/DiscoverBuildspecs.jpg
+   :scale: 75 %
+
+
 
 For every discovered buildspecs, buildtest will validate the buildspecs in the **parse**
 stage which is performed using `jsonschema.validate <https://python-jsonschema.readthedocs.io/en/stable/validate/#jsonschema.validate>`_ library.

docs/buildspecs/buildspec_overview.rst

@@ -359,22 +359,8 @@ this test, we define a duplicate tag **network** which is not allowed.
 .. literalinclude:: ../tutorials/invalid_tags.yml
     :language: yaml
 
-If we run this test and inspect the logs we will see an error message in schema validation:
 
-.. code-block:: console
-
-    2020-09-29 10:56:43,175 [parser.py:179 - _validate() ] - [INFO] Validating test - 'duplicate_string_tags' with schemafile: script-v1.0.schema.json
-    2020-09-29 10:56:43,175 [buildspec.py:397 - parse_buildspecs() ] - [ERROR] ['network', 'network'] is not valid under any of the given schemas
-
-    Failed validating 'oneOf' in schema['properties']['tags']:
-        {'oneOf': [{'type': 'string'},
-                   {'$ref': '#/definitions/list_of_strings'}]}
-
-    On instance['tags']:
-        ['network', 'network']
-
-If tags is a list, it must contain one item, therefore an empty list (i.e ``tags: []``)
-is invalid.
+If tags is a list, it must contain atleast **one** item.
 
 Customize Shell
 -----------------

docs/configuring_buildtest.rst

@@ -1,7 +1,7 @@
 .. _configuring_buildtest:
 
-Configuring buildtest
-======================
+How to configure buildtest
+===========================
 
 .. toctree::
    :maxdepth: 2

docs/gettingstarted/buildingtest.rst

@@ -254,34 +254,6 @@ can do the following:
 
     buildtest build -b tests --executor-type local
 
-.. _discover_buildspecs:
-
-Discover Buildspecs
---------------------
-
-Now, let's discuss how buildtest discovers buildspecs since there are several ways to build
-buildspecs.
-
-The buildspec search resolution is described as follows:
-
-- If file or directory specified by ``-b`` option doesn't exist we exit immediately.
-
-- If buildspec path is a directory, traverse directory recursively to find all ``.yml`` extensions
-
-- If buildspec path is a file, check if file extension is not ``.yml``,  exit immediately
-
-- If user specifies ``--tags`` or ``--executor`` we search in buildspec cache to discover buildspecs.
-
-Shown below is a diagram on how buildtest discovers buildspecs. The user can build buildspecs
-by ``--buildspec``, :ref:`--tags <build_by_tags>`, or :ref:`--executor <build_by_executor>`
-which will discover the buildspecs. You can :ref:`exclude buildspecs <exclude_buildspecs>`
-using ``--exclude`` option which is processed after discovering buildspecs. The
-excluded buildspecs are removed from list if found and final list of buildspecs
-is processed.
-
-.. image:: ../_static/DiscoverBuildspecs.jpg
-   :scale: 75 %
-
 .. _build_stage:
 
 Configure Build Stages

docs/index.rst

@@ -82,17 +82,28 @@ automate module load testing. For more details on lmodule see https://github.com
    getting_started
    buildspec_tutorial
 
+
 .. toctree::
    :maxdepth: 2
-   :caption: Reference
+   :caption: How-to-guides
 
    configuring_buildtest
    batch_support
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Explanation
+
    builder
+   buildtest_site
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
    features
    schema_examples
    facility_examples
-   buildtest_site
    references
 
 .. toctree::

docs/schema_examples.rst

@@ -3,12 +3,24 @@
 Buildtest Schemas
 ==========================
 
+buildtest uses JSON Schema for validating buildspecs and :ref:`buildtest configuration file <configuring_buildtest>`.
+The json schemas are published at https://buildtesters.github.io/buildtest/ and we
+provide a command line interface to view schema files and examples.
+
+Schema Naming Convention
+------------------------
+
+All schema files use the file extension **.schema.json** to distinguish itself
+as a json schema definition from an ordinary json file. The schema files are located
+in `buildtest/schemas <https://github.com/buildtesters/buildtest/tree/devel/buildtest/schemas>`_
+directory.
+
 .. _buildtest_schemas:
 
 CLI for buildtest schemas (``buildtest schema``)
 -------------------------------------------------
 
-buildtest uses JSON Schema for validating buildspecs and :ref:`buildtest configuration file <configuring_buildtest>`.
+
 You can use ``buildtest schema`` command to see the list of schemas
 supported by buildtest. The schema files are denoted by ``.schema.json`` file extension.
 
@@ -22,21 +34,11 @@ Shown below is the command usage of ``buildtest schema``
 
     .. command-output:: buildtest schema --help
 
-The json schemas are published at https://buildtesters.github.io/buildtest/ and we
-provide a command line interface to view schema files and examples. You must use the
-``--name`` option to select a schema, for instance if you want to view the JSON Schema for
+You must use the ``--name`` option to select a schema, for instance if you want to view the JSON Schema for
 **script.schema.json** you can run the following::
 
     buildtest schema --name script.schema.json --json
 
-Schema Naming Convention
-------------------------
-
-All schema files use the file extension **.schema.json** to distinguish itself
-as a json schema definition from an ordinary json file. The schema files are located
-in `buildtest/schemas <https://github.com/buildtesters/buildtest/tree/devel/buildtest/schemas>`_
-directory.
-
 Schema Files
 --------------