diff --git a/docs/builder.rst b/docs/builder.rst index 53b1fb055..3bdcd6865 100644 --- a/docs/builder.rst +++ b/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 `, or :ref:`--executor ` +which will discover the buildspecs. You can :ref:`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 `_ library. diff --git a/docs/buildspecs/buildspec_overview.rst b/docs/buildspecs/buildspec_overview.rst index db1d0f4c2..708ab7e35 100644 --- a/docs/buildspecs/buildspec_overview.rst +++ b/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 ----------------- diff --git a/docs/configuring_buildtest.rst b/docs/configuring_buildtest.rst index a41159f31..17fbb5dd5 100644 --- a/docs/configuring_buildtest.rst +++ b/docs/configuring_buildtest.rst @@ -1,7 +1,7 @@ .. _configuring_buildtest: -Configuring buildtest -====================== +How to configure buildtest +=========================== .. toctree:: :maxdepth: 2 diff --git a/docs/gettingstarted/buildingtest.rst b/docs/gettingstarted/buildingtest.rst index dadd43b6d..5c2455e22 100644 --- a/docs/gettingstarted/buildingtest.rst +++ b/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 `, or :ref:`--executor ` -which will discover the buildspecs. You can :ref:`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 diff --git a/docs/index.rst b/docs/index.rst index 74805a9ba..1a360acd5 100644 --- a/docs/index.rst +++ b/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:: diff --git a/docs/schema_examples.rst b/docs/schema_examples.rst index b3208ef14..884736ab1 100644 --- a/docs/schema_examples.rst +++ b/docs/schema_examples.rst @@ -3,12 +3,24 @@ Buildtest Schemas ========================== +buildtest uses JSON Schema for validating buildspecs and :ref:`buildtest configuration file `. +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 `_ +directory. + .. _buildtest_schemas: CLI for buildtest schemas (``buildtest schema``) ------------------------------------------------- -buildtest uses JSON Schema for validating buildspecs and :ref:`buildtest configuration file `. + 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 `_ -directory. - Schema Files --------------