doc: improve fixtures doc, add API

doc/api.rst

@@ -0,0 +1,9 @@
+API documentation
+=================
+
+Below are some of the classes API used by |ptx|.
+
+.. autoclass:: pytest_executable.script_runner.ScriptRunner
+   :members:
+
+.. autoclass:: pytest_executable.settings.Tolerances

doc/conf.py

@@ -17,9 +17,9 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'pytest-executable'
-copyright = '2019, C-S'
-author = 'C-S'
+project = "pytest-executable"
+copyright = "2019, C-S"
+author = "C-S"
 
 
 # -- General configuration ---------------------------------------------------
@@ -28,15 +28,12 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.mathjax',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.autodoc',
-    'sphinx_autodoc_typehints',
-    'sphinxcontrib.spelling',
+    "sphinx.ext.napoleon",
+    "sphinxcontrib.spelling",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -49,19 +46,15 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 
 # -- Extension configuration -------------------------------------------------
-mathjax_path = 'mathjax-v3.0.0_tex-svg-full.js'
-
-autodoc_docstring_signature = False
-
 rst_prolog = """
 .. _pytest: https://docs.pytest.org
 .. |ptx| replace:: *pytest-executable*
@@ -70,3 +63,27 @@
 .. |yaml| replace:: :file:`test_case.yaml`
 .. |runner| replace:: *runner shell script*
 """
+
+
+from sphinx.ext import autodoc
+
+# class DocsonlyMethodDocumenter(autodoc.MethodDocumenter):
+#   def format_args(self):
+#     return None
+#
+# autodoc.add_documenter(DocsonlyMethodDocumenter)
+
+
+class SimpleDocumenter(autodoc.MethodDocumenter):
+    objtype = "simple"
+
+    # do not indent the content
+    content_indent = ""
+
+    # do not add a header to the docstring
+    def add_directive_header(self, sig):
+        pass
+
+
+def setup(app):
+    app.add_autodocumenter(SimpleDocumenter)

doc/fixtures.rst

@@ -23,7 +23,7 @@
 Fixtures
 ========
 
-The purpose of test fixtures is to ease the writing of test functions by
+The purpose of the test fixtures is to ease the writing of test functions by
 providing informations and data automatically. You may find more documentation
 on |pytest| fixture in its `official documentation
 <https://docs.pytest.org/en/latest/fixture.html>`_. We describe here the
@@ -33,32 +33,39 @@ see :ref:`builtin-test-module`.
 Runner fixture
 --------------
 
-This fixture is used to execute |runner|. The :py:data:`runner` object provided
-by the fixture can be executed with the :py:meth:`run` method which will return
-the exit status of the script execution. The value **0** of the exit status
-means a successful execution.
+The :py:data:`runner` fixture is used to execute the |runner|. It will create
+the runner script in the output directory of a test case from the script passed
+to the pytest command line with the option :option:`--exe-runner`. The
+placeholders in the script are replaced with their actual values determined
+from the settings in the yaml file and the output path. The runner object
+passed by the fixture can be executed with the :py:meth:`run` method which will
+return the exit status of the script execution. The value of the exit status
+shall be **0** when the execution is successful.
+
+When the runner script is not passed to :option:`--exe-runner`, a function that
+uses this fixture will be skipped.
 
 Output path fixture
 -------------------
 
-This fixture is used to get the absolute path to the output directory of a test
-case. It provides the :py:data:`output_path` variable that holds a `Path`_
-object.
+The :py:data:`output_path` fixture provides the absolute path to the output
+directory of a test case as a `Path`_ object.
 
 .. _regression-path-fixtures:
 
 Regression path fixture
 -----------------------
 
-This fixture is used to get the paths to the reference data of a test case, see
-:ref:`yaml-ref`. If :option:`--exe-regression-root` is not used then the test
-functions that use the fixture are skipped. Otherwise, the test functions that
-use this fixture are called once per reference item (file or directory)
-declared in the references section of |yaml|. The fixture name is
-:py:data:`regression_file_path`, it's an object with the attributes:
+The :py:data:`regression_file_path` fixture provides the paths to the reference
+data of a test case, see :ref:`yaml-ref`. If :option:`--exe-regression-root` is
+not set then a test function that uses the fixture is skipped. Otherwise, a
+test function that use this fixture is called once per reference item (file or
+directory) declared in the references section of |yaml| (thanks to the
+`parametrize <https://docs.pytest.org/en/latest/parametrize.html>`_). The
+:py:data:`regression_file_path` object has the attributes:
 
 - :py:attr:`relative`: a `Path`_ object that contains the path to a reference
-  item relatively to the test case output directory.
+  item relatively to the output directory of the test case.
 - :py:attr:`absolute`: a `Path`_ object that contains the absolute path to a
   reference item.
 
@@ -70,9 +77,9 @@ path to the file that shall be compared to a reference file.
 Tolerances fixture
 ------------------
 
-This fixture is used to get the values of the tolerances defined in the |yaml|,
-see :ref:`yaml-tol`. It provides the :py:data:`tolerances` dictionary that
-binds a data name to an object that has 2 attributes:
+The :py:data:`tolerances` fixture provides the tolerances defined in the
+|yaml|, see :ref:`yaml-tol`. The :py:data:`tolerances` object is a dictionary
+that binds a data name to an object that has 2 attributes:
 
 - :py:attr:`rel`: the relative tolerance,
 - :py:attr:`abs`: the absolute tolerance.

doc/index.rst

@@ -31,6 +31,7 @@ Welcome to |ptx| documentation!
    post-processing
    fixtures
    test_executable
+   api
    changelog
 
 

src/pytest_executable/plugin.py

@@ -117,7 +117,7 @@ def pytest_addoption(parser):
 
 
 def pytest_sessionstart(session):
-    """Check the cli arguments."""
+    """Check the cli arguments and resolve their paths."""
     option = session.config.option
 
     # check options clash
@@ -215,28 +215,13 @@ def _get_settings(config: _pytest.config.Config, path: Path) -> Settings:
 
 @pytest.fixture(scope="module")
 def tolerances(request):
-    """Fixture that provides the settings from global and local test_case.yaml."""
+    """Fixture that provides the tolerances from the settings."""
     return _get_settings(request.config, request.node.fspath).tolerances
 
 
 @pytest.fixture(scope="module")
 def runner(request, create_output_tree, output_path):
-    """Fixture to execute the runner script or skip a test.
-
-    This fixture will create the runner script in the output directory of a
-    test case from the script passed to the pytest command line with the option
-    :option:`--exe-runner`. The placeholders in the script are replaced with
-    their actual values determined from the settings in the yaml file and the
-    output path. The runner object created by the fixture can be executed with
-    the :py:meth:`run` method which will return the exit code of the script
-    execution.
-
-    When the runner script is not passed to :option:`--exe-runner`, a function
-    that uses this fixture will be skipped.
-
-    Returns:
-        ScriptRunner object.
-    """
+    """Fixture to execute the runner script."""
     runner_path = request.config.option.exe_runner
     if runner_path is None:
         pytest.skip("no runner provided with --exe-runner")

src/pytest_executable/settings.py

@@ -34,7 +34,7 @@
 
 @dataclass
 class Tolerances:
-    """Fields comparison tolerances.
+    """Comparison tolerances.
 
     Attributes:
         rel: The relative tolerance.
@@ -47,15 +47,15 @@ class Tolerances:
 
 @dataclass
 class Settings:
-    """Test settings.
+    """Test settings container.
 
-    This dataclass contains the test settings read from a yaml file.
+    This contains the test settings read from a yaml file.
 
     Attributes:
-        runner: The settings used in the runner script.
+        runner: The settings for the script runner.
         marks: The pytest marks.
         references: The reference files path patterns.
-        tolerances: The fields comparison tolerances.
+        tolerances: The comparison tolerances.
     """
 
     runner: Dict[str, str]

tox.ini

@@ -41,7 +41,7 @@ commands =
 [testenv:doc]
 basepython = {[testenv:dev]basepython}
 deps = -r{toxinidir}/doc/requirements.txt
-skip_install = true
+usedevelop = true
 commands =
     sphinx-build {posargs:-E} -b html doc dist/doc