updating CONTRIBUTING.rst with section on building apidocs, automatin…

…g documentation tests and running pytest for regression testing

CONTRIBUTING.rst

@@ -92,31 +92,33 @@ Documentation
 buildtest documentation (https://buildtest.readthedocs.io/en/latest) is hosted by ReadTheDocs (https://readthedocs.org)
 which is a documentation platform for building and hosting your docs. buildtest project can be found at
 https://readthedocs.org/projects/buildtest/ which will show the recent builds and project setting. If you are interested
-in being a documentation maintainer, please contact Shahzeb Siddiqui <shahzebmsiddiqui@gmail.com> to enable access to
+in being a documentation maintainer, please contact **Shahzeb Siddiqui** (``shahzebmsiddiqui@gmail.com``) to enable access to
 this project. buildtest documentation is using sphinx (http://www.sphinx-doc.org/en/master/) to build the underlying
 documentation.
 
 buildtest documentation is hosted in ``docs`` found at the root of this repository. If you want to
 build the documentation you will need to make sure your python environment has all the packages defined by
 ``requirements.txt``.
 
-To install your python packages, you can run the following.
+To install your python packages, you can run the following::
 
-::
 
  pip install -r requirements.txt
 
 The file ``requirements.txt`` can be found at https://github.com/HPC-buildtest/buildtest-framework/blob/master/docs/requirements.txt
 
-To build your documentation simply run the following
+To build your documentation simply run the following::
 
-::
 
  cd docs
+ make clean
  make html
 
-This will build the sphinx project and generate all the html files. Once this process is complete you may want to view
-the documentation. If you have ``firefox`` in your system you can simply run the following
+It is best practice to run ``make clean`` to ensure sphinx will remove old html content from previous builds, but it is ok to
+skip ``make clean`` if you are making minor changes.
+
+Running ``make html`` will build the sphinx project and generate all the html files in ``docs/_build/html``. Once this process is
+complete you may want to view the documentation. If you have ``firefox`` in your system you can simply run the following
 
 ::
 
@@ -125,3 +127,61 @@ the documentation. If you have ``firefox`` in your system you can simply run the
 This will open a ``firefox`` session to the root of your documentation that was recently generated. You will want to
 make sure you have X11 forwarding in order for firefox to work properly. Refer to the ``Makefile`` to see all of the
 make tags and you may run ``make`` or ``make help`` for additional help
+
+Building buildtest API Docs
+----------------------------
+
+In order to build the API library for buildtest you can run the following::
+
+ make apidocs
+
+This will run the target ``apidocs`` which is running a ``sphinx-apidocs`` command. The target location for api docs is in ``docs/api`` so
+you may want to remove all the apidocs before regenerate them to ensure you have the right contents uploaded for the push. This can be
+done by running the following::
+
+ git rm -rf api/*
+
+Next, build the api docs::
+
+ make apidocs
+
+Then add, commit and push content::
+
+ git add api/*
+ git commit -m <MESSAGE>
+ git push
+
+Automate Documentation Examples
+--------------------------------
+
+buildtest has a script in ``$BUILDTEST_ROOT/src/buildtest/docgen/main.py`` to automate documentation examples. This script can be run as follows::
+
+ cd $BUILDTEST_ROOT
+ python $BUILDTEST_ROOT/src/buildtest/docgen/main.py
+
+This assumes your buildtest environment is setup, the script will write documentation test examples in ``docs/docgen``. Consider running this script when **adding**, **modifying**, or **removing** documentation examples. Once the test are complete, you will want to add the
+tests, commit and push as follows::
+
+ git add docs/docgen
+ git commit -m <MESSAGE>
+ git push
+
+Buildtest Regression Test
+--------------------------
+
+buildtest has a suite of regression tests to verify the state of buildtest. These tests are located in ``$BUILDTEST_ROOT/tests`` and
+the tests can be executed using ``pytest``.
+
+To run all the tests you can run the following::
+
+ pytest tests/
+
+To print passed test with output consider running with option::
+
+ pytest -rP tests/
+
+If you are interested in failed tests run with option::
+
+ pytest -rf tests/
+
+Refer to pytest documentation (https://docs.pytest.org/en/latest/contents.html) for list of all options.