Allow to specify paths in the configuration file, document the cli and configuration values. (#23)

Author: tobiasraabe

.github/workflows/continuous-integration-workflow.yml

@@ -35,7 +35,7 @@ jobs:
 
       - name: Run unit tests and doctests.
         shell: bash -l {0}
-        run: tox -e pytest -- -m "unit or (not integration and not end_to_end)" --cov=./src --cov-report=xml -n auto
+        run: tox -e pytest -- src tests -m "unit or (not integration and not end_to_end)" --cov=./src --cov-report=xml -n auto
 
       - name: Upload coverage report for unit tests and doctests.
         if: runner.os == 'Linux' && matrix.python-version == '3.8'
@@ -44,7 +44,7 @@ jobs:
 
       - name: Run integration tests.
         shell: bash -l {0}
-        run: tox -e pytest -- -m integration --cov=./src --cov-report=xml -n auto
+        run: tox -e pytest -- src tests -m integration --cov=./src --cov-report=xml -n auto
 
       - name: Upload coverage reports of integration tests.
         if: runner.os == 'Linux' && matrix.python-version == '3.8'
@@ -53,7 +53,7 @@ jobs:
 
       - name: Run end-to-end tests.
         shell: bash -l {0}
-        run: tox -e pytest -- -m end_to_end --cov=./src --cov-report=xml -n auto
+        run: tox -e pytest -- src tests -m end_to_end --cov=./src --cov-report=xml -n auto
 
       - name: Upload coverage reports of end-to-end tests.
         if: runner.os == 'Linux' && matrix.python-version == '3.8'

README.rst

@@ -58,7 +58,7 @@ Installation
 pytask is available on `Anaconda.org <https://anaconda.org/pytask/pytask>`_. Install the
 package with
 
-.. code-block:: bash
+.. code-block:: console
 
     $ conda config --add channels conda-forge --add channels pytask
     $ conda install pytask
@@ -93,7 +93,7 @@ Here are some details:
 
 To execute the task, type the following command on the command-line
 
-.. code-block::
+.. code-block:: console
 
     $ pytask
     ========================= Start pytask session =========================

docs/api.rst

@@ -17,6 +17,8 @@ all releases are available on `Anaconda.org <https://anaconda.org/pytask/pytask>
 - :gh:`18` changes the documentation theme to alabaster.
 - :gh:`19` adds some changes related to ignored folders.
 - :gh:`20` fixes copying code examples in the documentation.
+- :gh:`23` allows to specify paths via the configuration file, documents the cli and
+  configuration options.
 
 
 0.0.5 - 2020-08-12

docs/changes.rst

@@ -8,6 +8,8 @@
 import os
 import sys
 
+import sphinx
+
 
 sys.path.insert(0, os.path.abspath("../src"))
 
@@ -38,8 +40,9 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
-    "autoapi.extension",
     "sphinx_autodoc_typehints",
+    "sphinx_click",
+    "autoapi.extension",
 ]
 
 # List of patterns, relative to source directory, that match files and directories to
@@ -54,7 +57,15 @@
 # Configuration for autodoc.
 autosummary_generate = True
 add_module_names = False
-autodoc_mock_imports = ["attr", "click", "networkx", "pluggy", "pony"]
+# Actually irrelevant since sphinx-click needs to import everything to build the cli.
+autodoc_mock_imports = [
+    "attr",
+    "click",
+    "click_default_group",
+    "networkx",
+    "pluggy",
+    "pony",
+]
 
 # Remove prefixed $ for bash, >>> for Python prompts, and In [1]: for IPython prompts.
 copybutton_prompt_text = r"\$ |>>> |In \[\d\]: "
@@ -106,3 +117,12 @@
     "font_family": '"Avenir Next", Calibri, "PT Sans", sans-serif',
     "head_font_family": '"Avenir Next", Calibri, "PT Sans", sans-serif',
 }
+
+
+def setup(app: "sphinx.application.Sphinx") -> None:
+    app.add_object_type(
+        "confval",
+        "confval",
+        objname="configuration value",
+        indextemplate="pair: %s; configuration value",
+    )

docs/conf.py

@@ -10,3 +10,4 @@ systems in general as well as its design.
    why_do_i_need_a_build_system
    why_another_build_system
    design
+   pluggy

docs/explanations/index.rst

@@ -25,12 +25,12 @@ pytask
 This is the documentation of pytask. You can install the package from `Anaconda.org
 <https://anaconda.org/pytask/pytask>`_ with
 
-.. code-block:: bash
+.. code-block:: console
 
     $ conda config --add channels conda-forge --add channels pytask
     $ conda install pytask
 
-The documentation has four parts.
+The documentation has four central parts.
 
 .. raw:: html
 
@@ -103,9 +103,10 @@ The documentation has four parts.
     reference_guides/index
 
 
+Here are some additional resources.
+
 .. toctree::
    :maxdepth: 1
 
    glossary
    changes
-   api

docs/reference_guides/pluggy.rst renamed to docs/explanations/pluggy.rst

@@ -0,0 +1,8 @@
+The command line interface
+==========================
+
+This section documents the command line interface of pytask.
+
+.. click:: _pytask.cli:cli
+    :show-nested:
+    :prog: pytask

docs/index.rst

@@ -0,0 +1,139 @@
+The configuration
+=================
+
+This document lists all options to configure pytask via the configuration files.
+
+
+The basics
+----------
+
+To learn about the basics visit the :doc:`tutorial
+<../tutorials/how_to_configure_pytask>`.
+
+
+Truthy and falsy values
+-----------------------
+
+For some of the configuration values you need truthy or falsy values. pytask recognizes
+the following values.
+
+- truthy: ``True``, ``true``, ``1``.
+- falsy: ``False``, ``false``, ``0``.
+
+Additionally, the following values are interpreted as None which is neither truthy or
+falsy.
+
+- ``None``
+- ``none``
+
+
+The options
+-----------
+
+.. confval:: ignore
+
+    pytask can ignore files and directories and exclude some tasks or reduce the
+    duration of the collection.
+
+    To ignore some file/folder via the command line, use the ``--ignore`` flag multiple
+    times.
+
+    .. code-block:: console
+
+        $ pytask --ignore some_file.py --ignore some_directory/*
+
+    Or, use the configuration file:
+
+    .. code-block:: ini
+
+        # For single entries only.
+        ignore = some_file.py
+
+        # Or single and multiple entries.
+        ignore =
+            some_directory/*
+            some_file.py
+
+
+.. confval:: markers
+
+    pytask uses markers to attach additional information to task functions. To see which
+    markers are available, type
+
+    .. code-block:: console
+
+        $ pytask markers
+
+    on the command-line interface.
+
+    If you use a marker which has not been configured, you will get a warning. To
+    silence the warning and document the marker, provide the following information in
+    your pytask configuration file.
+
+    .. code-block:: ini
+
+        markers =
+            wip: Work-in-progress. These are tasks which I am currently working on.
+
+
+.. confval:: paths
+
+    If you want to collect tasks from specific paths without passing the names via the
+    command line, you can add the paths to the configuration file. Paths passed via the
+    command line will overwrite the configuration value.
+
+    .. code-block:: ini
+
+        # For single entries only.
+        paths = src
+
+        # Or single and multiple entries.
+        paths =
+            folder_1
+            folder_2/task_2.py
+
+
+.. confval:: pdb
+
+    If you want to enter the interactive debugger whenever an error occurs, pass the
+    flag to the command line interface
+
+    .. code-block:: console
+
+        pytask --pdb
+
+    or use a truthy configuration value.
+
+    .. code-block:: ini
+
+        pdb = True
+
+
+.. confval:: strict_markers
+
+    If you want to raise an error for unregistered markers, pass
+
+    .. code-block:: console
+
+        pytask --strict-markers
+
+    or set the option to a truthy value.
+
+    .. code-block:: ini
+
+        strict_markers = True
+
+
+.. confval:: trace
+
+    If you want to enter the interactive debugger in the beginning of each task, use
+
+    .. code-block:: console
+
+        pytask --trace
+
+    or set this option to a truthy value.
+
+    .. code-block:: ini
+
+        trace = True

docs/reference_guides/command_line_interface.rst

@@ -7,6 +7,17 @@ additional details on the inner workings of pytask.
 .. toctree::
    :maxdepth: 1
 
-   pluggy
+   command_line_interface
+   configuration
    hookspecs
    marks
+
+
+The following documents are auto-generated and not carefully edited. They provide direct
+access to the source code and the docstrings.
+
+.. toctree::
+   :titlesonly:
+
+   /autoapi/pytask/index
+   /autoapi/_pytask/index

docs/reference_guides/configuration.rst

@@ -7,3 +7,13 @@ dependencies:
   - sphinx-copybutton
   - sphinx-autodoc-typehints
   - sphinx-autoapi
+  - sphinx-click
+
+  # Package dependencies necessary for sphinx-click
+  - attrs
+  - click
+  - click-default-group
+  - networkx
+  - pexpect
+  - pluggy
+  - pony >= 0.7.13

docs/reference_guides/index.rst

@@ -7,7 +7,7 @@ task was renamed and the old version still exists.
 To clean directories from files which are not recognized by pytask, enter the directory
 and type
 
-.. code-block::
+.. code-block:: console
 
     $ pytask clean
     =============================== Start pytask session ===============================
@@ -34,7 +34,7 @@ If you want to remove the files, there exist two other modes for :option:`pytask
 If you want to delete whole folders instead of only the files in them, use
 :option:`pytask clean -d`.
 
-.. code-block::
+.. code-block:: console
 
     $ pytask clean -d
     =============================== Start pytask session ===============================
@@ -51,26 +51,6 @@ If you want to delete whole folders instead of only the files in them, use
 Command line options
 --------------------
 
-.. program:: pytask clean
-
-To clean your project, pytask offers a clean command similar to ``git clean``.
-
-.. option:: pytask clean [OPTIONS] [PATHS]...
-
-The command line interface has the following options.
-
-.. option:: -m, --mode [dry-run|interactive|force]
-
-    The mode for the clean command.
-
-    - ``dry-run`` shows which files and directories would be removed.
-    - ``force`` removes all files and directories without further confirmation.
-    - ``interactive`` allows the user to choose for every file and directory.
-
-.. option:: -d, --directories
-
-    Allows to remove whole directories if all its content can be removed as well.
-
-.. option:: -q, --quiet
-
-    Do not show which files are removed.
+.. click:: _pytask.cli:cli
+    :commands: clean
+    :prog: pytask