Merge pull request #887 from buildtesters/v0.11.0_release

v0.11.0 release

CHANGELOG.rst

@@ -1,8 +1,8 @@
 CHANGELOG
 =========
 
-v0.11.0
------------
+v0.11.0 (Sep 9th, 2021)
+-------------------------
 
 In this release we tweaked the core implementation of buildtest for running test. Now we make use of asynchronous test execution and
 job submission to get parallelization of jobs. Previously we were running jobs serially which was quite slow. We are using
@@ -17,6 +17,7 @@ batch job submission which was done in `#863 <https://github.com/buildtesters/bu
 - Added alias for subcommands - `#860 <https://github.com/buildtesters/buildtest/pull/860/>`_
 - Remove `batch` property from buildtest - `#868 <https://github.com/buildtesters/buildtest/pull/868/>`_
 - Add support to disable executors in configuration file via ``disable`` property -  `#870 <https://github.com/buildtesters/buildtest/pull/870/>`_
+- Add `napolean <https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_ and `intersphinx <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ extension and rewrite docstring for entire codebase in Google Style see `#885 <https://github.com/buildtesters/buildtest/pull/885>`_
 
 v0.10.2 (Aug 16, 2021)
 ----------------------

buildtest/__init__.py

@@ -1,3 +1,3 @@
-BUILDTEST_VERSION = "0.10.2"
+BUILDTEST_VERSION = "0.11.0"
 __version__ = BUILDTEST_VERSION
 BUILDTEST_COPYRIGHT = "Copyright (c) 2021, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy), Shahzeb Siddiqui, and Vanessa Sochat. All rights reserved."

docs/contributing/build_documentation.rst

@@ -48,6 +48,40 @@ pages by running the following::
 
 Please refer to the ``Makefile`` to see list of tags or run ``make`` for additional help.
 
+Sphinx
+-------
+
+The documentation is built via `Sphinx <https://www.sphinx-doc.org/en/master/>`_ using
+`reStructuredText (rST) <https://docutils.sourceforge.io/rst.html>`_ as its markup language. When
+you run `make` you are running `sphinx-build <https://www.sphinx-doc.org/en/master/man/sphinx-build.html>`_ command
+which will generate the documentation.
+
+Sphinx will read the configuration file `conf.py <https://github.com/buildtesters/buildtest/blob/devel/docs/conf.py>`_ used
+for building the project. We have enabled a couple `sphinx extensions <https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`_
+in our project to customize our documentation
+
+API Generation
+---------------
+
+We make use of `Sphinx AutoAPI <https://sphinx-autoapi.readthedocs.io/en/latest/>`_ to generate
+buildtest API documentation that is hosted on https://buildtest.readthedocs.io/en/devel/api/index.html.
+The Sphinx AutoAPI configuration is configured in sphinx configuration file `conf.py`. For more details
+on configuration options see https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
+
+Command Line Documentation
+----------------------------
+
+We make use of `sphinx-argparse <https://sphinx-argparse.readthedocs.io/en/stable/index.html>`_ to generate
+documentation for buildtest command line that is hosted at https://buildtest.readthedocs.io/en/devel/command.html.
+In order to use this tool one must install this package and enable the extension in sphinx configuration.
+
+DocStrings
+-----------
+
+We have enabled `napolean extension <https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_ to support
+Google style docstring. Please follow this format when you are writting docstring for buildtest codebase. For more details
+on google style see: https://google.github.io/styleguide/pyguide.html
+
 Automate Documentation Examples
 --------------------------------
 

docs/what_is_buildtest.rst

@@ -108,6 +108,7 @@ Timeline
     :header: "Date", "Version", "Description"
     :widths: 20, 20, 80
 
+    **Sep 9th 2021**, "`v0.11.0 <https://github.com/buildtesters/buildtest/releases/tag/v0.11.0>`_", "Reimplement core implementation of running and polling jobs using asynchronous job submission. In addition we added several new commands including: **buildtest cd**, **buildtest path** and **buildtest path** and we enable alias for sub-commands."
     **Aug 16th 2021**, "`v0.10.2 <https://github.com/buildtesters/buildtest/releases/tag/v0.10.2>`_", "Add support for multi executor support in buildspec via ``executors`` property. Add new commands ``buildtest report summary`` for summary of report file. The ``buildtest buildspec show`` command shows content of buildspec file given a test name. The ``buildtest edit`` command can be used to edit buildspec and validate with JSON schema upon closing file. In this release, we added ``buildtest inspect buildspec`` command to view records based on buildspec file."
     **Jul 30th 2021**, "`v0.10.1 <https://github.com/buildtesters/buildtest/releases/tag/v0.10.1>`_", "Add new commands ``buildtest buildspec summary``, ``buildtest buildspec invalid`` to show summary of buildspec cache and invalid buildspecs. Add ``buildtest build --filter`` to filter buildspecs during build. Add ``--terse`` option for several commands including **buildtest history list**, **buildtest report**, **buildtest buildspec find**. Add new command ``buildtest inspect query`` for querying test records. Added support for ``metrics`` property for defining arbitrary metrics in buildspec based on environment variable, variables or regular expression on stdout/stderr"
     **Jul 13th 2021**, "`v0.10.0 <https://github.com/buildtesters/buildtest/releases/tag/v0.10.0>`_", "In this release we added `spack <https://spack.readthedocs.io/>`__ support in buildtest by creating a new schema to write buildspecs that will generate spack commands. For more details see :ref:`spack schema <spack_schema>`. We added bash completion for buildtest commands which is enabled when installing buildtest. We added a new command ``buildtest buildspec validate``  that can be used for validating buildspecs  with JSON Schema."