Skip to content

[bugfix] Various documentation fixes #1771

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 12, 2021
Merged

[bugfix] Various documentation fixes #1771

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
573f518
Various documentation fixes
Feb 11, 2021
e150c37
Address PR comments
Feb 12, 2021
1909a2e
Merge branch 'master' into docs/various-fixes
Feb 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 19 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,12 @@ The stages of this pipeline take care of all the system interaction details, suc
Writing system regression tests in a high-level modern programming language, like Python, poses a great advantage in organizing and maintaining the tests.
Users can create their own test hierarchies, create test factories for generating multiple tests at the same time and also customize them in a simple and expressive way.

Please visit the project's documentation [page](https://reframe-hpc.readthedocs.io/) for all the details!

## Getting ReFrame

ReFrame is almost ready to run just after you clone it from Github.
## Installation

ReFrame is fairly easy to install.
All you need is Python 3.6 or above and to run its bootstrap script:

```bash
Expand All @@ -40,37 +42,19 @@ cd reframe
./bin/reframe -V
```

### Other installation ways

You can also install ReFrame through the following channels:

- Through [PyPI](https://pypi.org/project/ReFrame-HPC/):

```
pip install reframe-hpc
```

- Through [Spack](https://spack.io/):

```
spack install reframe
```

- Through [EasyBuild](https://easybuild.readthedocs.io/):

```
eb easybuild/easyconfigs/r/ReFrame/ReFrame-VERSION.eb -r
```
If you want a specific release, please refer to the documentation [page](https://reframe-hpc.readthedocs.io/en/stable/started.html).

Finally, you may access all previous versions of ReFrame [here](https://github.com/eth-cscs/reframe/releases).

### Running the unit tests

## Documentation
You can optionally run the framework's unit tests with the following command:

You may find the official documentation of the latest release and the current master in the following links:
```bash
./test_reframe.py -v
```

- [Latest release](https://reframe-hpc.readthedocs.io/en/stable)
- [Current master](https://reframe-hpc.readthedocs.io/en/latest)
NOTE: Unit tests require a functional C compiler, available through the `cc` command, that is also able to recognize the ``-O2`` option.
The [GNU Make](https://www.gnu.org/software/make/) build tool is also needed.


### Building the documentation locally
Expand Down Expand Up @@ -102,21 +86,18 @@ However, they can serve as a very good starting point for implementing your syst

You can get in contact with the ReFrame community in the following ways:

### Mailing list

For keeping up with the latest news about ReFrame, posting questions and, generally getting in touch with other users and the developers, you may follow the mailing list: [reframe@sympa.cscs.ch](mailto:reframe@sympa.cscs.ch).

Only subscribers may send messages to the list.
To subscribe, please send an empty message to [reframe-subscribe@sympa.cscs.ch](mailto:reframe-subscribe@sympa.cscs.ch).
### Slack

For unsubscribing, you may send an empty message to [reframe-unsubscribe@sympa.cscs.ch](mailto:reframe-unsubscribe@sympa.cscs.ch).
Please join the community's [Slack channel](https://reframe-slack.herokuapp.com) for keeping up with the latest news about ReFrame, posting questions and, generally getting in touch with other users and the developers.

### Slack
### Mailing list

You may also reach the community through Slack [here](https://reframe-slack.herokuapp.com).
You may also [subscribe](mailto:reframe-subscribe@sympa.cscs.ch) to the [mailing list](mailto:reframe@sympa.cscs.ch).
Only subscribers can send messages to the list.
For unsubscribing, you may send an empty message [here](mailto:reframe-unsubscribe@sympa.cscs.ch).


## Contributing back

ReFrame is an open-source project and we welcome third-party contributions.
ReFrame is an open-source project and we welcome and encourage contributions!
Check out our Contribution Guide [here](https://github.com/eth-cscs/reframe/wiki/contributing-to-reframe).
2 changes: 1 addition & 1 deletion docs/config_reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ System Configuration
- ``tmod32``: A synonym of ``tmod``.
- ``tmod4``: The `new environment modules <http://modules.sourceforge.net/>`__ implementation (versions older than 4.1 are not supported).
- ``lmod``: The `Lua implementation <https://lmod.readthedocs.io/en/latest/>`__ of the environment modules.
- ``spack``: `Spack <https://spack.readthedocs.io/en/latest/>`'s built-in mechanism for managing modules.
- ``spack``: `Spack <https://spack.readthedocs.io/en/latest/>`__'s built-in mechanism for managing modules.
- ``nomod``: This is to denote that no modules system is used by this system.

.. versionadded:: 3.4
Expand Down
4 changes: 3 additions & 1 deletion docs/configure.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ Each system is associated with a set of properties, which in this case are the f
* ``hostnames``: This is a list of hostname patterns following the `Python Regular Expression Syntax <https://docs.python.org/3/library/re.html#regular-expression-syntax>`__, which will be used by ReFrame when it tries to automatically select a configuration entry for the current system.
* ``modules_system``: In our example, this is only defined for Piz Daint and refers to the environment modules system that should be used for loading environment modules on this system.
In this case, the classic Tcl implementation of the `environment modules <https://sourceforge.net/projects/modules/files/Modules/modules-3.2.10/>`__.
For a complete list of the supported modules systems, see `here <config_reference.html#.systems[].modules_system>`__.
* ``partitions``: The list of partitions that are defined for this system.
Each partition is defined as a separate object.
We devote the rest of this section in system partitions, since they are an essential part of ReFrame's configuration.
Expand Down Expand Up @@ -157,7 +158,7 @@ Let's see how logging is defined in our example configuration, which also repres

Logging is configured under the ``logging`` section of the configuration, which is a list of logger objects.
Unless you want to configure logging differently for different systems, a single logger object is enough.
Each logger object is associated with a logging level stored in the ``level`` property and has a set of logging handlers that are actually responsible for handling the actual logging records.
Each logger object is associated with a `logging level <config_reference.html#.logging[].level>`__ stored in the ``level`` property and has a set of logging handlers that are actually responsible for handling the actual logging records.
ReFrame's output is performed through the logging mechanism, meaning that if you don't specify any logging handler, you will not get any output from ReFrame!
The ``handlers`` property of the logger object holds the actual handlers.
Notice that you can use multiple handlers at the same time, which enables you to feed ReFrame's output to different sinks and at different verbosity levels.
Expand All @@ -166,6 +167,7 @@ These are the following:

* ``type``: This is the type of the handler, which determines its functionality.
Depending on the handler type, handler-specific properties may be allowed or required.
For a complete list of available log handler types, see `here <config_reference.html#.logging[].handlers[].type>`__.
* ``level``: The cut-off level for messages reaching this handler.
Any message with a lower level number will be filtered out.
* ``format``: A format string for formatting the emitted log record.
Expand Down
2 changes: 1 addition & 1 deletion docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ Publications
:maxdepth: 2

started
configure
tutorials
configure
topics
usecases
migration_2_to_3
Expand Down
182 changes: 50 additions & 132 deletions docs/started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,82 +7,92 @@ Requirements

* Python 3.6 or higher.
Python 2 is not supported.
* Required Python packages can be found in the ``requirements.txt`` file.
See :ref:`install-from-source` for more information on how to install ReFrame from source.
* The required Python packages are the following:


---------------------
Optional Requirements
---------------------

If you want to run the framework's unit tests, you will need a C compiler available through `cc` that is able to compile a "Hello, World!" program and recognize the ``-O3`` option, as well as the `GNU Make <https://www.gnu.org/software/make/>`__ build tool.
.. literalinclude:: ../requirements.txt


.. note::
.. versionchanged:: 2.8

A functional TCL modules system is no more required. ReFrame can now operate without a modules system at all.

.. note::
.. versionchanged:: 3.0

Support for Python 3.5 has been dropped.



Getting the Framework
---------------------

ReFrame's latest stable version is available through different channels:
Stable ReFrame releases are available through different channels.

- As a `PyPI <https://pypi.org/project/ReFrame-HPC/>`__ package:

.. code:: bash
-----
Spack
-----

pip install reframe-hpc
ReFrame is available as a `Spack <https://spack.io/>`__ package:

.. note::
.. code:: bash

spack install reframe

The above method performs a bare installation of ReFrame not including unittests and tutorial examples.

There are the following variants available:

- As a `Spack <https://spack.io/>`__ package:
- ``+docs``: This will install the man pages of ReFrame.
- ``+gelf``: This will install the bindings for handling `Graylog <https://docs.graylog.org/>`__ log messages.

.. code:: bash

spack install reframe
---------
EasyBuild
---------


- As an `EasyBuild <https://easybuild.readthedocs.io/en/latest/>`__ package:
ReFrame is available as an `EasyBuild <https://easybuild.readthedocs.io/en/latest/>`__ package:

.. code:: bash

.. code:: bash
eb ReFrame-VERSION.eb -r

eb easybuild/easyconfigs/r/ReFrame/ReFrame-VERSION.eb -r

This will install the man pages as well as the `Graylog <https://docs.graylog.org/>`__ bindings.

.. _install-from-source:

-------------------------------
Getting the Latest and Greatest
-------------------------------
----
PyPI
----

If you want the latest development version or any pre-release, you can clone ReFrame from Github:

ReFrame is available as a `PyPI <https://pypi.org/project/ReFrame-HPC/>`__ package:

.. code:: bash

git clone https://github.com/eth-cscs/reframe.git
pip install reframe-hpc


Pre-release versions are denoted with the ``devX`` suffix and are `tagged <https://github.com/eth-cscs/reframe/releases>`__ in the repository.
Preparing and running ReFrame from source is pretty straightforward.
All you need is a Python 3.6+ installation with ``pip``:
This is a bare installation of the framework.
It will not install the documentation, the tutorial examples or the bindings for handling `Graylog <https://docs.graylog.org/>`__ log messages.

.. code:: bash

git clone https://github.com/eth-cscs/reframe.git
cd reframe
./bootstrap.sh
./bin/reframe -V
------
Github
------

Any ReFrame version can be very easily installed directly from Github:

.. code-block:: bash

pushd /path/to/install/prefix
git clone -q --depth 1 --branch VERSION_TAG https://github.com/eth-cscs/reframe.git
pushd reframe && ./bootstrap.sh && popd
export PATH=$(pwd)/bin:$PATH
popd

The ``VERSION_TAG`` is the version number prefixed by ``v``, e.g., ``v3.5.0``.
The ``./bootstrap.sh`` script will fetch ReFrame's requirements under its installation prefix.
It will not set the ``PYTHONPATH``, so it will not affect the user's Python installation.
The ``./bootstrap.sh`` has two additional variant options:

- ``+docs``: This will also build the documentation.
- ``+pygelf``: This will install the bindings for handling `Graylog <https://docs.graylog.org/>`__ log messages.

.. note::
.. versionadded:: 3.1
Expand All @@ -100,98 +110,6 @@ Auto-completion is supported for Bash, Tcsh and Fish shells.



Running the Unit Tests
----------------------

You can optionally run the framework's unit tests to make sure that everything is set up correctly:


.. code:: bash

./test_reframe.py -v

The output should look like the following:

.. code:: bash

======================================== test session starts =========================================
platform darwin -- Python 3.7.3, pytest-4.3.0, py-1.8.0, pluggy-0.9.0 -- /usr/local/opt/python/bin/python3.7
cachedir: .pytest_cache
rootdir: /Users/karakasv/Repositories/reframe, inifile:
collected 697 items

unittests/test_argparser.py::test_arguments PASSED [ 0%]
unittests/test_argparser.py::test_parsing PASSED [ 0%]
unittests/test_argparser.py::test_option_precedence PASSED [ 0%]
unittests/test_argparser.py::test_option_with_config PASSED [ 0%]
unittests/test_argparser.py::test_option_envvar_conversion_error PASSED [ 0%]
unittests/test_buildsystems.py::TestMake::test_emit_from_buildsystem PASSED [ 0%]
unittests/test_buildsystems.py::TestMake::test_emit_from_env PASSED [ 1%]
unittests/test_buildsystems.py::TestMake::test_emit_no_env_defaults PASSED [ 1%]
unittests/test_buildsystems.py::TestCMake::test_emit_from_buildsystem PASSED [ 1%]
unittests/test_buildsystems.py::TestCMake::test_emit_from_env PASSED [ 1%]
unittests/test_buildsystems.py::TestCMake::test_emit_no_env_defaults PASSED [ 1%]
unittests/test_buildsystems.py::TestAutotools::test_emit_from_buildsystem PASSED [ 1%]
unittests/test_buildsystems.py::TestAutotools::test_emit_from_env PASSED [ 1%]
unittests/test_buildsystems.py::TestAutotools::test_emit_no_env_defaults PASSED [ 2%]
unittests/test_buildsystems.py::TestSingleSource::test_emit_from_env PASSED [ 2%]
unittests/test_buildsystems.py::TestSingleSource::test_emit_no_env PASSED [ 2%]
unittests/test_check_filters.py::TestCheckFilters::test_have_cpu_only PASSED [ 2%]
unittests/test_check_filters.py::TestCheckFilters::test_have_gpu_only PASSED [ 2%]
unittests/test_check_filters.py::TestCheckFilters::test_have_name PASSED [ 2%]
unittests/test_check_filters.py::TestCheckFilters::test_have_not_name PASSED [ 2%]
unittests/test_check_filters.py::TestCheckFilters::test_have_prgenv PASSED [ 3%]
unittests/test_check_filters.py::TestCheckFilters::test_have_tags PASSED [ 3%]
unittests/test_check_filters.py::TestCheckFilters::test_invalid_regex PASSED [ 3%]
unittests/test_check_filters.py::TestCheckFilters::test_partition PASSED [ 3%]
unittests/test_cli.py::test_check_success PASSED [ 3%]
unittests/test_cli.py::test_check_submit_success SKIPPED [ 3%]
unittests/test_cli.py::test_check_failure PASSED [ 3%]
<... output omitted ...>
unittests/test_utility.py::TestPpretty::test_simple_types PASSED [ 95%]
unittests/test_utility.py::TestPpretty::test_mixed_types PASSED [ 95%]
unittests/test_utility.py::TestPpretty::test_obj_print PASSED [ 95%]
unittests/test_utility.py::TestChangeDirCtxManager::test_change_dir_working PASSED [ 95%]
unittests/test_utility.py::TestChangeDirCtxManager::test_exception_propagation PASSED [ 95%]
unittests/test_utility.py::TestMiscUtilities::test_allx PASSED [ 95%]
unittests/test_utility.py::TestMiscUtilities::test_decamelize PASSED [ 96%]
unittests/test_utility.py::TestMiscUtilities::test_sanitize PASSED [ 96%]
unittests/test_utility.py::TestScopedDict::test_construction PASSED [ 96%]
unittests/test_utility.py::TestScopedDict::test_contains PASSED [ 96%]
unittests/test_utility.py::TestScopedDict::test_delitem PASSED [ 96%]
unittests/test_utility.py::TestScopedDict::test_iter_items PASSED [ 96%]
unittests/test_utility.py::TestScopedDict::test_iter_keys PASSED [ 96%]
unittests/test_utility.py::TestScopedDict::test_iter_values PASSED [ 97%]
unittests/test_utility.py::TestScopedDict::test_key_resolution PASSED [ 97%]
unittests/test_utility.py::TestScopedDict::test_scope_key_name_pseudoconflict PASSED [ 97%]
unittests/test_utility.py::TestScopedDict::test_setitem PASSED [ 97%]
unittests/test_utility.py::TestScopedDict::test_update PASSED [ 97%]
unittests/test_utility.py::TestReadOnlyViews::test_mapping PASSED [ 97%]
unittests/test_utility.py::TestReadOnlyViews::test_sequence PASSED [ 97%]
unittests/test_utility.py::TestOrderedSet::test_concat_files PASSED [ 98%]
unittests/test_utility.py::TestOrderedSet::test_construction PASSED [ 98%]
unittests/test_utility.py::TestOrderedSet::test_construction_empty PASSED [ 98%]
unittests/test_utility.py::TestOrderedSet::test_construction_error PASSED [ 98%]
unittests/test_utility.py::TestOrderedSet::test_difference PASSED [ 98%]
unittests/test_utility.py::TestOrderedSet::test_intersection PASSED [ 98%]
unittests/test_utility.py::TestOrderedSet::test_operators PASSED [ 98%]
unittests/test_utility.py::TestOrderedSet::test_reversed PASSED [ 99%]
unittests/test_utility.py::TestOrderedSet::test_str PASSED [ 99%]
unittests/test_utility.py::TestOrderedSet::test_union PASSED [ 99%]
unittests/test_utility.py::TestOrderedSet::test_unique_abs_paths PASSED [ 99%]
unittests/test_versioning.py::TestVersioning::test_comparing_versions PASSED [ 99%]
unittests/test_versioning.py::TestVersioning::test_version_format PASSED [ 99%]
unittests/test_versioning.py::TestVersioning::test_version_validation PASSED [100%]

============================== 620 passed, 77 skipped in 64.58 seconds ===============================


You will notice that several tests will be skipped.
ReFrame uses a generic configuration by default, so that it can run on any system.
As a result, all tests for scheduler backends, environment modules, container platforms etc. will be skipped.
As soon as you configure ReFrame specifically for your system, you may rerun the test suite using your system configuration file by passing the ``--rfm-user-config=CONFIG_FILE``.


Where to Go from Here
---------------------

Expand Down
2 changes: 1 addition & 1 deletion docs/tutorial_advanced.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -674,7 +674,7 @@ First, we need to enable the container platform support in ReFrame's configurati
:lines: 38-58
:emphasize-lines: 15-20

For each partition, users can define a list of container platforms supported using the :js:attr:`container_platforms` configuration parameter.
For each partition, users can define a list of container platforms supported using the :js:attr:`container_platforms` `configuration parameter <config_reference.html#.systems[].partitions[].container_platforms>`__.
In this case, we define the `Singularity <https://sylabs.io>`__ platform, for which we set the :js:attr:`modules` parameter in order to instruct ReFrame to load the ``singularity`` module, whenever it needs to run with this container platform.

The following test will use a Singularity container to run:
Expand Down
Loading