doc: improve readme and small doc fixes

README.rst

@@ -8,18 +8,26 @@ Pytest-executable
     :target: https://pypi.org/project/pytest-executable
 
 .. image:: https://readthedocs.org/projects/pytest-executable/badge/?version=stable
-    :target: https://pytest-executable.readthedocs.io/en/latest/?badge=stable
+    :target: https://pytest-executable.readthedocs.io/en/stable/?badge=stable
     :alt: Documentation Status
 
-`pytest-executable` is a `pytest`_ plugin for checking and validating
-executables. This project is still young, but already used in a professional
-environment.
+``pytest-executable`` is a `pytest`_ plugin for simplifying the black-box
+testing of an executable, be it written in python or not. It helps to avoid
+writing the boilerplate test code to spawn subprocesses, to handle the output
+and references directory trees and to define the execution context. It
+integrates naturally with standard test scripts written for pytest. This plugin
+is originally intended for testing executables that create scientific data but
+it may hopefully be helpful for other kinds of executables.
+
+This project is still young, but already used in a professional environment.
+
 
 Documentation
 -------------
 
 The project documentation is available `online`_.
 
+
 Installation
 ------------
 
@@ -29,9 +37,10 @@ Install using `pip <http://pip-installer.org/>`_:
 
     pip install pytest-executable
 
-A `pytest-executable` package will soon be available in the Conda-Forge (just a
+A ``pytest-executable`` package will soon be available in Conda-Forge (just a
 matter of free time).
 
+
 Contributing
 ------------
 
@@ -41,22 +50,25 @@ time).
 Please fill an issue on the `Github issue tracker`_ for any bug report, feature
 request or question.
 
+
 Authors
 -------
 
 -  `Antoine Dechaume`_ - *Project creator and maintainer*
 
+
 Copyright and License
 ---------------------
 
 Copyright 2020, `CS GROUP`_
 
-`pytest-executable` is a free and open source software, distributed under the
+``pytest-executable`` is a free and open source software, distributed under the
 Apache License 2.0. See the `LICENSE.txt`_ file for more information, or the
 `quick summary`_ of this license on `tl;drLegal`_ website.
 
+
 .. _pytest: https://docs.pytest.org/en/latest
-.. _online: https://pytest-executable.readthedocs.io/en/stable
+.. _online: https://pytest-executable.readthedocs.io
 .. _`doc`: doc
 .. _documentation: https://pytest-executable.readthedocs.io/en/stable/installation.html
 .. _Github issue tracker: https://github.com/CS-SI/pytest-executable/issues

doc/tutorial.rst → doc/how-to-use.rst

@@ -15,8 +15,8 @@
 .. See the License for the specific language governing permissions and
 .. limitations under the License.
 
-Usage
-=====
+How to use
+==========
 
 The |ptx| tool can be used in a wide variety of ways, the following sections
 explain how.
@@ -28,39 +28,39 @@ Run |executable| only
 :command:`pytest --runner <path/to/runner> <path/to/tests/inputs> -k runner`
 
 This command will execute |executable| for all the test cases that are found in
-the inputs tree under :file:`path/to/tests/inputs`. A test case is identified
-by a directory that contains a |yaml| file. For each of the test cases found,
-|ptx| will create an output directory with the same directory hierarchy and
-run the cases in that output directory. By default, the root directory of the
-output tree :file:`tests-output`, this can be changed with the option
+the input tree under :file:`path/to/tests/inputs`. A test case is identified by
+a directory that contains a |yaml| file. For each of the test cases found,
+|ptx| will create an output directory with the same directory hierarchy and run
+the cases in that output directory. By default, the root directory of the
+output tree is :file:`tests-output`, this can be changed with the option
 :option:`--output-root`. Finally, the :option:`-k runner` option instructs
 |pytest| to only execute the |executable| runner and nothing more, see
 :ref:`filter` for more informations on doing only some of the processing.
 
-For instance, if the test inputs tree contains::
+For instance, if the tests input tree contains::
 
    path/to/tests/inputs
    ├── dir-1
-   │   ├── case.input
+   │   ├── input
    │   └── test_case.yaml
    └── dir-2
-       ├── case.input
+       ├── input
        └── test_case.yaml
 
-Then the output tree is::
+Then the tests output tree is::
 
    tests-output
    ├── dir-1
-   │   ├── case.input -> path/to/tests/inputs/dir-1/case.input
-   │   ├── case.output
+   │   ├── input -> path/to/tests/inputs/dir-1/input
+   │   ├── output
    │   ├── executable.stderr
    │   ├── executable.stdout
    │   ├── run_executable.sh
    │   ├── run_executable.stderr
    │   └── run_executable.stdout
    ├── dir-2
-       ├── case.input -> path/to/tests/inputs/dir-2/case.input
-       ├── case.output
+       ├── input -> path/to/tests/inputs/dir-2/input
+       ├── output
        ├── executable.stderr
        ├── executable.stdout
        ├── run_executable.sh
@@ -70,11 +70,13 @@ Then the output tree is::
 For a given test case, for instance :file:`tests-output/dir-1`,
 the output directory contains:
 
-case.output
-   the output file produced by the execution of |executable|, in practice there can be any number of ouput files and directories produced.
+output
+   the output file produced by the execution of |executable|, in practice there
+   can be any number of output files and directories produced.
 
-case.input
-    a symbolic link to the file in the test case input directory, in pratice there can be any number of input files.
+input
+    a symbolic link to the file in the test input directory, in pratice
+    there can be any number of input files.
 
 executable.stderr
     contains the error messages from the |executable| execution
@@ -83,30 +85,32 @@ executable.stdout
     contains the log messages from the |executable| execution
 
 run_executable.sh
-    Executing this script directly from a console shall produce the same results as when it is
-    executed by |ptx|. This script is intended to be as much as possible
-    independent of the execution context such that it can be executed
-    independently of |ptx| in a reproductible way, i.e. it is self contained
-    and does not depend on the shell context. :file:`run_executable.stderr` contains the
-    error messages from the |run_executable| execution
+    executing this script directly from a console shall produce the same
+    results as when it is executed by |ptx|. This script is intended to be as
+    much as possible independent of the execution context such that it can be
+    executed independently of |ptx| in a reproductible way, i.e. it is self
+    contained and does not depend on the shell context.
+
+run_executable.stderr
+    contains the error messages from the |run_executable| execution
 
 run_executable.stdout
     contains the log messages from the |run_executable| execution
 
-If you need to manually run |executable| for a test case, for debugging purposes
-for instance, just go to its output directory, for instance :command:`cd
-tests-output/dir-1`, and execute |run_executable|.
+If you need to manually run |executable| for a test case, for debugging
+purposes for instance, just go to its output directory, for instance
+:command:`cd tests-output/dir-1`, and execute |run_executable|.
 
 
 Do default regression checking without running executable
 ---------------------------------------------------------
 
 :command:`pytest --regression-root <path/to/tests/references> <path/to/tests/inputs> --overwrite-output`
 
-We assume that |executable| results have already been produced for the test cases
-considered. This is not enough though because the output directory already
-exists and |ptx| will by default prevent the user from silently modifying
-any existing test output directories. In that case, the option
+We assume that |executable| results have already been produced for the test
+cases considered. This is not enough though because the output directory
+already exists and |ptx| will by default prevent the user from silently
+modifying any existing test output directories. In that case, the option
 :option:`--overwrite-output` shall be used. The above command line will compare
 the results in the default output tree with the references, if the existing
 |executable| results are in a different directory then you need to add the path

doc/index.rst

@@ -68,7 +68,7 @@ result files required for performing the checks.
    :caption: Contents:
 
    usage
-   tutorial
+   how-to-use
    test-case
    post-processing
    fixtures

doc/test-case.rst

@@ -22,22 +22,20 @@ Add a test case
 
 A test case is composed of a directory with:
 
-- the |executable| input files
-- a |yaml| file with basic settings
-- optionnal |pytest| and python module for adding checks and post-processes
+- the input files of the |executable|
+- a |yaml| file with |ptx| settings
+- optionnal |pytest| and python modules for additionnal tests
 
-The |executable| input files shall use the naming convention :file:`case.labs`
-and :file:`case.pbd`. Among the optionnal modules, there shall be at least one
-that is discoverable by |pytest|, i.e. a python module which name starts with
-:file:`test_` and which contains at least one function which also starts with
-**test_**.
+Among the optionnal modules, there shall be at least one that is discoverable
+by |pytest|, i.e. a python module which name starts with :file:`test_` and
+which contains at least one function which also starts with **test_**.
 
 .. note::
 
    A test case directory shall not contain any of the files created by the
    execution of |executable| or of the processing defined in the python modules,
    otherwise they may badly interfere with the execution of the testing tool.
-   In other words, do not run anything in the input directory.
+   In other words: do not run the |executable| in the input directory.
 
 The |yaml| file is used by |ptx| for several things. When this file is
 found, |ptx| will create the test case output directory, then identify the
@@ -56,7 +54,9 @@ following sections.
 Number of parallel processes
 ----------------------------
 
-To change the number of parallel processes:
+This parameter is not used by directly by |ptx| for running the |executable|,
+but is intended to be used in |run_executable|. To change the number of
+parallel processes:
 
 .. code-block:: yaml
 
@@ -67,12 +67,11 @@ Regression reference files
 --------------------------
 
 Reference files are used to do regression checks on the files produced by
-|executable|. The regression is
-done by comparing the files with a given tolerance (explained in the next
-section). The `references` setting shall contain a list of paths to the files
-to be compared. A path shall be defined relatively to the test case directory,
-it may use any shell pattern like :file:`**`, :file:`*`, :file:`?`, for
-instance:
+|executable|. The regression is done by comparing the files with a given
+tolerance (explained in the next section). The `references` setting shall
+contain a list of paths to the files to be compared. A path shall be defined
+relatively to the test case directory, it may use any shell pattern like
+:file:`**`, :file:`*`, :file:`?`, for instance:
 
 .. code-block:: yaml
 

doc/test_case_yaml.rst

@@ -20,6 +20,7 @@
 Builtin test module
 ===================
 
-This is the python module executed when the testing tool finds a :file:`test_case.yaml`, this module can be used as an example for writing new test modules.
+This is the python module executed when the testing tool finds a |yaml|, this
+module can be used as an example for writing new test modules.
 
 .. literalinclude:: ../src/pytest_executable/test_case_yaml.py

setup.cfg

@@ -5,9 +5,9 @@ name = pytest_executable
 author = Antoine Dechaume
 url = https://www.github.com/CS-SI/pytest-executable
 description = pytest plugin for testing executables
-long_description = file: README.md
-long_description_content_type = text/markdown
-license = Apache Software License
+long_description = file: README.rst, CHANGELOG.rst
+long_description_content_type = text/x-rst
+license = Apache Software License 2.0
 license_file = LICENSE.txt
 classifiers =
     Operating System :: POSIX :: Linux