Merge pull request #92 from LUMC/docimprovement

Slight documentation improvements.

Author: rhpvorderman

HISTORY.rst

@@ -9,9 +9,9 @@ Changelog
 
 version 1.3.0-dev
 ---------------------------
-
++ Added missing ``help`` section for ``--tag``.
 + Documentation: added usage chapter for pytest-workflow specific options.
-+ Added missing `help` for `--tag`.
++ Documentation: updated Cromwell example.
 + Removed redundant references to pylint in code comments and CI.
 + Remove Codacy from the CI.
 

docs/examples.rst

@@ -40,20 +40,13 @@ repository with the following contents:
 
     {
     "final_workflow_outputs_dir": "test-output",
-    "use_relative_output_paths": true,
-    "default_runtime_attributes": {
-      "docker_user": "$EUID"
-      }
+    "use_relative_output_paths": true
     }
 
 ``final_workflow_outputs_dir`` will make sure all the files produced in the
 workflow will be copied to the ``final_workflow_outputs_dir``.
 ``use_relative_output_paths`` will get rid of all the Cromwell specific folders
-such as ``call-myTask`` etc. The ``default_runtime_attributes`` are only
-necessary when using docker containers. It will make sure all the files are
-created by the same user that runs the test (docker containers run as root by
-default). This will ensure that files can be deleted by pytest-workflow
-afterwards.
+such as ``call-myTask`` etc.
 
 The following yaml file tests a Cromwell pipeline. In this case Cromwell is
 installed via conda. The conda installation adds a wrapper to Cromwell so it

docs/installation.rst

@@ -10,15 +10,15 @@ In a virtual environment
 
 - Create a new python3 virtual environment.
 - Make sure your virtual environment is activated.
-- Install using pip ``pip install pytest-workflow``
+- Install using pip ``pip install pytest-workflow``.
 
 On Ubuntu or Debian
 -------------------
 
 - This requires the ``python3`` and ``python3-pip`` packages to be installed.
 - Installing
 
-  - system-wide: ``sudo python3 -m pip install pytest-workflow``
+  - system-wide: ``sudo python3 -m pip install pytest-workflow``.
   - for your user only (no sudo needed):
     ``python3 -m pip install --user pytest-workflow``
 - ``pytest`` can now be run with ``python3 -m pytest``.
@@ -43,4 +43,4 @@ To install with conda:
   - If you want to use pytest-workflow together with bioconda you can follow
     `the instructions here
     <https://bioconda.github.io/index.html#set-up-channels>`_.
-- ``conda install pytest-workflow``
+- ``conda install pytest-workflow``.

docs/running_pytest_workflow.rst

@@ -14,6 +14,12 @@ The workflows are run automatically. Each workflow gets its own temporary
 directory to run. The ``stdout`` and ``stderr`` of the workflow command are
 also saved to this directory to ``log.out`` and ``log.err`` respectively.
 
+To check the progress of a workflow while it is running you can use ``tail -f``
+on the ``stdout`` or ``stderr`` file of the workflow. The locations of these
+files are reported in the log as soon as a workflow is started.
+
+Specific pytest options for pytest workflow
+------------------------------------------------
 
 .. argparse::
     :module: pytest_workflow.plugin
@@ -53,10 +59,6 @@ To run multiple workflows simultaneously you can use
 of workflows that can be run simultaneously. This will speed up things if
 you have enough resources to process these workflows simultaneously.
 
-To check the progress of a workflow while it is running you can use ``tail -f``
-on the ``stdout`` or ``stderr`` file of the workflow. The locations of these
-files are reported in the log as soon as a workflow is started.
-
 Running specific workflows
 ----------------------------
 To run a specific workflow use the ``--tag`` flag. Each workflow is tagged with

docs/writing_tests.rst

@@ -88,18 +88,15 @@ workflow.
 
     @pytest.mark.workflow(name='files containing numbers')
     def test_div_by_three(workflow_dir):
-        number_file = workflow_dir / pathlib.Path("123.txt")
-
-        with number_file.open('rt') as file_h:
-            number_file_content = file_h.read()
-
+        number_file = pathlib.Path(workflow_dir, "123.txt")
+        number_file_content = number_file.read_text()
         assert int(number_file_content) % 3 == 0
 
 The ``@pytest.mark.workflow(name='files containing numbers')`` marks the test
-as belonging to a workflow named 'files containing numbers'. The mark can also
-be written without the explicit ``name`` key as ``@pytest.mark.workflow('files
-containing nummbers')``. This test will only run if the workflow 'files
-containing numbers' has run.
+as belonging to a workflow named ``files containing numbers``. The mark can
+also be written without the explicit ``name`` key as
+``@pytest.mark.workflow('files containing nummbers')``. This test will only run
+if the workflow 'files containing numbers' has run.
 
 ``workflow_dir`` is a fixture. It does not work without a
 ``pytest.mark.workflow('workflow_name')`` mark.  This is a

src/pytest_workflow/plugin.py

@@ -44,7 +44,7 @@ def pytest_addoption(parser: PytestParser):
         action="store_true",
         help="Keep temporary directories where workflows are run for "
              "debugging purposes. This also triggers saving of stdout and "
-             "stderr in the workflow directory",
+             "stderr in the workflow directory.",
         dest="keep_workflow_wd")
     parser.addoption(
         "--kwdof", "--keep-workflow-wd-on-fail",