diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..54936b2 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,19 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/source/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +formats: all + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.8 + install: + - requirements: docs/requirements.txt diff --git a/README.md b/README.md index a1c2521..f76c09f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +[![Documentation Status](https://readthedocs.org/projects/ats/badge/?version=main)](https://ats.readthedocs.io/en/main/?badge=main) + # ATS ## Description @@ -10,6 +12,8 @@ across a variety of HPC platforms. ATS usage and expectations vary among its user base. This also applies to how ATS is installed. Below are a few variations that users may find helpful. +For more information, please check our [documentation](https://ats.readthedocs.io). + #### "Global" install A "global" install really means a widely available Python executable with ATS diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..93120e6 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +docutils<0.18 diff --git a/docs/source/conf.py b/docs/source/conf.py index 9c51078..8c83203 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -41,7 +41,7 @@ # General information about the project. project = 'ATS' -copyright = '2011, Lawrence Livermore National Security LLC' +copyright = '2021, Lawrence Livermore National Security LLC' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/docs/source/index.rst b/docs/source/index.rst index 3e77329..6e6de62 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,16 +1,193 @@ -.. ATS documentation master file, created by - sphinx-quickstart on Wed Jan 19 20:59:15 2011. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +######################### +The Automated Test System +######################### + + +******************** +Purpose and Features +******************** + +.. index:: ATS features + +The Automated Testing System (ATS) is an open-source, Python-based tool for +automating the running of tests of an application. ATS can test any program +that can signal success or failure via its exit status. + +ATS is distributed, introspective, and scalable. + +* It is distributed in two senses. First, there is no central database + of tests to run. Tests may be spread over many directories and usually + adding a test in a subdirectory is entirely a local operation. + +* Introspective means that a test can be runnable by someone who is not an + expert, yet runnable with different arguments by someone who is. An + application test may contain within itself, in comments, directions for how to + run itself in one or more ways. An expert may run these tests normally using + his application; but when ATS runs it, it runs the application according to + the special comments within the input. + +* Depending on the available resources, the execution of the tests can be done + over many processors and hosts, in parallel. Distributed execution and + test specification helps ATS stay scalable. + +Other features of ATS include: + +* A test may depend on another test, and will not be executed + unless their parent test succeeds. + +* Tests may be filtered out (that is, not executed) in many ways. + These may include number of processors, time limit, platform, or other + user-defined criteria. + +* A level may be given to each test, and used to stratify a test suite into + subsets of increasing thoroughness. + +* ATS is extensible. + The ats driver script does almost nothing except import the + ats module and call the ats.manager.main() method. It may suit your + purposes to make a different driver that does things before or after this + invocation. The ats script uses the assets of the module ats + to provide a command line interface-type testing system. Other + interfaces, such as a GUI interface, are possible. + +* ATS makes it easy in particular to postprocess the results of the testing by + registering routines to be executed after the tests have completed, but before + exiting. + + * A facility is provided to make it easy to port ATS to new machines + such as parallel processors and multi-noded distributed machines, or to take + advantage of multiple cores. The 'stock' ATS will run up to two tests at + once, each of them standard serial jobs (np = 1 in what follows). + +While ATS input can be written using the full power of Python, the basic +operations require only a few statements written in a special vocabulary that +is not be hard to learn. For example:: + + test(executable="/my/path/to/my/code", + clas="-input mydeck delta=3", + np=3) + +executes the given executable with the given command-line arguments (clas), +launching the job is parallel on 3 processors. + +.. index:: function signatures + +.. note:: A note on function signatures + While this document assumes you can learn the basics of Python on your own, + function signatures require careful understanding. In Python, the definition + of a function parameter can have one or two asterisks in front of a name. + + * When calling such a function, in the place of a parameter with one asterisk + in front of it, you can give zero or more comma-separated values + as a value, which the function will receive as a list. + + * When a parameter name has two asterisks in front of it in the function + definition, you can give zero or more comma-separated keyword = value pairs + when you call it, which the function will receive as a dictionary. + + For example, the ATS ``source`` function has the signature:: + + source(*paths, **vocabulary) + + which means any of the following are legitimate calls to it:: + + source('foo.py') + source('foo.py', 'goo.py') + source('foo.py', physics="on", music = "off") + source(physics="on", music = "off") + source() + + As it happens, the last of these doesn't do anything, but it is a legitimate + call. + + .. note:: + All of the *paths* arguments must come before the first of the + *vocabulary* arguments. + +Download and Install +==================== + +Installation of ATS is easy. Unpack the distribution and in the top-level +directory execute:: + + python setup.py install + +Public releases are at http://code.google.com/p/ats + +The README.txt file contains installation instructions. ATS has been tested with +Python 2.6 or later, available at http://python.org. + +ATS should translate to Python 3 by using the 2to3 utility but this has not yet been tried. + +ATS should work, or be made to work, on any system which can run Python via +a command window. In particular it works out of the box on any Linux or Mac +system. ATS works on Windows but experience there is limited. + +History +======= + +ATS was written by Paul F. Dubois at Lawrence Livermore National Laboratory, +(LLNL) in about 2003. Although an open-source release was made, the software +was highly oriented to the LLNL computer systems and one particular simulation, +ATS has been in continuous use since then. + +A revision in 2010-11 has compartmentalized the LLNL-specific system details, +and we have added new features to make the software more generally applicable +and more easily portable. + +The support team at LLNL includes Nu Ai Tang, T. J. Alumbaugh, and Ines Heinz. +You can contact the author at dubois1@llnl.gov. For help with the LLNL +features contact tang10@llnl.gov. + +ATS was written to test scientific simulations, although it can be used for +any program that can be run with a command-line, does not require interaction, +and which can signal its own success or failure via its exit status (or be +executed via a shell program with those properties). + +In general scientific programs do not produce predictable printed output, and so +comparison of output files, so common in the testing literature, is not normally +useful.They also are generally long-running and resource-consuming; hence ATS +emphasises filtering, parallel execution, and prioritization under user control. +Provision for supporting batch execution is also provided. + +LLNL Notes +========== + +.. index:: LLNL-specific features + +The LC distribution includes an LC directory containing definitions for the +local machines and the batch system. To make use of the features of LC machines +you will need to set either SYS_TYPE or MACHINE_TYPE. To install the LC machines, run:: + + python setup.py install + +in the LC directory after you have done so in the main ATS directory. + +For help join the mailing list ats@lists.llnl.gov. + +About The Documentation +======================= + +This document is licensed under the terms of the LICENSE.txt file +in the ATS distribution. + +This documentation is written in reStructuredText, the standard language +used by the Python documentation project. You should find the source, +available in the distribution, readable even without rendering. It can be if +desired rendered into plain text files, web pages, PDF files, and other +formats using the tools of the *Sphinx* project. The source files +are located in the ``source`` subdirectory of the ``docs`` directory. The +Makefile in the ``docs`` directory will render the documents into +the ``build`` subdirectory if appropriate parts of Sphinx have been +installed. + +If you install ``setuptools`` into your Python, you can get Sphinx with:: + + easy_install -U Sphinx .. toctree:: :maxdepth: 3 - intro andyroid ats appendix - - - - diff --git a/docs/source/intro.rst b/docs/source/intro.rst deleted file mode 100644 index fb1692d..0000000 --- a/docs/source/intro.rst +++ /dev/null @@ -1,187 +0,0 @@ -######################### -The Automated Test System -######################### - - -******************** -Purpose and Features -******************** - -.. index:: ATS features - -The Automated Testing System (ATS) is an open-source, Python-based tool for -automating the running of tests of an application. ATS can test any program -that can signal success or failure via its exit status. - -ATS is distributed, introspective, and scalable. - -* It is distributed in two senses. First, there is no central database - of tests to run. Tests may be spread over many directories and usually - adding a test in a subdirectory is entirely a local operation. - -* Introspective means that a test can be runnable by someone who is not an - expert, yet runnable with different arguments by someone who is. An - application test may contain within itself, in comments, directions for how to - run itself in one or more ways. An expert may run these tests normally using - his application; but when ATS runs it, it runs the application according to - the special comments within the input. - -* Depending on the available resources, the execution of the tests can be done - over many processors and hosts, in parallel. Distributed execution and - test specification helps ATS stay scalable. - -Other features of ATS include: - -* A test may depend on another test, and will not be executed - unless their parent test succeeds. - -* Tests may be filtered out (that is, not executed) in many ways. - These may include number of processors, time limit, platform, or other - user-defined criteria. - -* A level may be given to each test, and used to stratify a test suite into - subsets of increasing thoroughness. - -* ATS is extensible. - The ats driver script does almost nothing except import the - ats module and call the ats.manager.main() method. It may suit your - purposes to make a different driver that does things before or after this - invocation. The ats script uses the assets of the module ats - to provide a command line interface-type testing system. Other - interfaces, such as a GUI interface, are possible. - -* ATS makes it easy in particular to postprocess the results of the testing by - registering routines to be executed after the tests have completed, but before - exiting. - - * A facility is provided to make it easy to port ATS to new machines - such as parallel processors and multi-noded distributed machines, or to take - advantage of multiple cores. The 'stock' ATS will run up to two tests at - once, each of them standard serial jobs (np = 1 in what follows). - -While ATS input can be written using the full power of Python, the basic -operations require only a few statements written in a special vocabulary that -is not be hard to learn. For example:: - - test(executable="/my/path/to/my/code", - clas="-input mydeck delta=3", - np=3) - -executes the given executable with the given command-line arguments (clas), -launching the job is parallel on 3 processors. - -.. index:: function signatures - -.. note:: A note on function signatures - While this document assumes you can learn the basics of Python on your own, - function signatures require careful understanding. In Python, the definition - of a function parameter can have one or two asterisks in front of a name. - - * When calling such a function, in the place of a parameter with one asterisk - in front of it, you can give zero or more comma-separated values - as a value, which the function will receive as a list. - - * When a parameter name has two asterisks in front of it in the function - definition, you can give zero or more comma-separated keyword = value pairs - when you call it, which the function will receive as a dictionary. - - For example, the ATS ``source`` function has the signature:: - - source(*paths, **vocabulary) - - which means any of the following are legitimate calls to it:: - - source('foo.py') - source('foo.py', 'goo.py') - source('foo.py', physics="on", music = "off") - source(physics="on", music = "off") - source() - - As it happens, the last of these doesn't do anything, but it is a legitimate - call. - - .. note:: - All of the *paths* arguments must come before the first of the - *vocabulary* arguments. - -Download and Install -==================== - -Installation of ATS is easy. Unpack the distribution and in the top-level -directory execute:: - - python setup.py install - -Public releases are at http://code.google.com/p/ats - -The README.txt file contains installation instructions. ATS has been tested with -Python 2.6 or later, available at http://python.org. - -ATS should translate to Python 3 by using the 2to3 utility but this has not yet been tried. - -ATS should work, or be made to work, on any system which can run Python via -a command window. In particular it works out of the box on any Linux or Mac -system. ATS works on Windows but experience there is limited. - -History -======= - -ATS was written by Paul F. Dubois at Lawrence Livermore National Laboratory, -(LLNL) in about 2003. Although an open-source release was made, the software -was highly oriented to the LLNL computer systems and one particular simulation, -ATS has been in continuous use since then. - -A revision in 2010-11 has compartmentalized the LLNL-specific system details, -and we have added new features to make the software more generally applicable -and more easily portable. - -The support team at LLNL includes Nu Ai Tang, T. J. Alumbaugh, and Ines Heinz. -You can contact the author at dubois1@llnl.gov. For help with the LLNL -features contact tang10@llnl.gov. - -ATS was written to test scientific simulations, although it can be used for -any program that can be run with a command-line, does not require interaction, -and which can signal its own success or failure via its exit status (or be -executed via a shell program with those properties). - -In general scientific programs do not produce predictable printed output, and so -comparison of output files, so common in the testing literature, is not normally -useful.They also are generally long-running and resource-consuming; hence ATS -emphasises filtering, parallel execution, and prioritization under user control. -Provision for supporting batch execution is also provided. - -LLNL Notes -========== - -.. index:: LLNL-specific features - -The LC distribution includes an LC directory containing definitions for the -local machines and the batch system. To make use of the features of LC machines -you will need to set either SYS_TYPE or MACHINE_TYPE. To install the LC machines, run:: - - python setup.py install - -in the LC directory after you have done so in the main ATS directory. - -For help join the mailing list ats@lists.llnl.gov. - -About The Documentation -======================= - -This document is licensed under the terms of the LICENSE.txt file -in the ATS distribution. - -This documentation is written in reStructuredText, the standard language -used by the Python documentation project. You should find the source, -available in the distribution, readable even without rendering. It can be if -desired rendered into plain text files, web pages, PDF files, and other -formats using the tools of the *Sphinx* project. The source files -are located in the ``source`` subdirectory of the ``docs`` directory. The -Makefile in the ``docs`` directory will render the documents into -the ``build`` subdirectory if appropriate parts of Sphinx have been -installed. - -If you install ``setuptools`` into your Python, you can get Sphinx with:: - - easy_install -U Sphinx -