Refactor command line interface to subcommands, add -c/--config option and clean command. (#17)

Author: tobiasraabe

.conda/meta.yaml

@@ -26,6 +26,7 @@ requirements:
     - setuptools
     - attrs >=17.4.0
     - click
+    - click-default-group
     - networkx
     - pluggy
     - pony >=0.7.13

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
     -   id: check-yaml
         exclude: meta.yaml
     -   id: debug-statements
-        exclude: (debugging\.py|main\.py)
+        exclude: (debugging\.py|build\.py)
     -   id: end-of-file-fixer
 -   repo: https://github.com/asottile/pyupgrade
     rev: v2.7.2
@@ -51,6 +51,11 @@ repos:
     rev: 0.8.1rc3
     hooks:
     -   id: doc8
+-   repo: https://github.com/econchick/interrogate
+    rev: 1.2.0
+    hooks:
+    -   id: interrogate
+        args: [-v, --fail-under=40, src, tests]
 -   repo: https://github.com/codespell-project/codespell
     rev: v1.17.1
     hooks:

README.rst

@@ -1,7 +1,6 @@
 .. raw:: html
 
-    <img src="docs/_static/images/pytask_w_text.png" alt="pytask"
-         width="50%">
+    <img src="docs/_static/images/pytask_w_text.png" alt="pytask" width="50%">
 
 ------
 
@@ -30,17 +29,27 @@ Features
 In its highest aspirations, pytask tries to be pytest as a build system. Its features
 include:
 
-- Automatic discovery of tasks.
+- **Automatic discovery of tasks.**
 
-- It tracks dependencies and products as well as the source file of a task to evaluate
-  whether it needs to be re-executed.
+- **Lazy evaluation.** If a task or its dependencies have not changed, do not
+  execute it.
 
-- pytask does not stop if one task fails, but continues execution for all collected
-  tasks. Tasks which depend on failed tasks are automatically skipped.
+- **Debug mode.** Jump into the debugger if a task fails and get quick feedback.
 
-- Easily extensible since its architecture is based on `pluggy
+- **Select tasks via expressions.** Run only a subset of tasks with expressions and
+  marker expressions known from pytest.
+
+- **Easily extensible with plugins**. pytask's architecture is based on `pluggy
   <https://pluggy.readthedocs.io/en/latest/>`_, a plugin management and hook calling
-  framework.
+  framework which enables you to adjust pytask to your needs.
+
+
+Why do I need a build system?
+-----------------------------
+
+Read the `section in the documentation <https://pytask-dev.readthedocs.io/en/latest/
+explanations/why_do_i_need_a_build_system.html>`_ if you do not know or are not
+convinced that you need a build system.
 
 
 Installation
@@ -87,13 +96,13 @@ To execute the task, type the following command on the command-line
 .. code-block::
 
     $ pytask
-    =============================== Start pytask session ===============================
+    ========================= Start pytask session =========================
     Platform: linux -- Python 3.x.y, pytask 0.x.y, pluggy 0.x.y
     Root: xxx
     Collected 1 task(s).
 
     .
-    ============================ 1 succeeded in 1 second(s) ============================
+    ====================== 1 succeeded in 1 second(s) ======================
 
 
 Demo

docs/_static/images/pytask_w_text.png

@@ -6,11 +6,14 @@ chronological order. Releases follow `semantic versioning <https://semver.org/>`
 all releases are available on `Anaconda.org <https://anaconda.org/pytask/pytask>`_.
 
 
-0.0.6 - 2020-08-22
+0.0.6 - 2020-xx-xx
 ------------------
 
 - :gh:`16` reduces the traceback generated from tasks, failure section in report, fix
   error passing a file path to pytask, add demo to README.
+- :gh:`17` changes the interface to subcommands, adds ``"-c/--config"`` option to pass a
+  path to a configuration file and adds ``pytask clean``, a command to clean your
+  project.
 
 
 0.0.5 - 2020-08-12

docs/_static/images/pytask_w_text.svg

@@ -7,5 +7,6 @@ systems in general as well as its design.
 .. toctree::
    :maxdepth: 1
 
+   why_do_i_need_a_build_system
    why_another_build_system
    design

docs/changes.rst

@@ -0,0 +1,38 @@
+Why do I need a build system?
+=============================
+
+A common problem people face when analyzing data (or building software, etc.) is that
+their workflows involve multiple tasks. The tasks might have a order in which they need
+to be executed because they build upon each other.
+
+For example, a workflow of an empirical research project consists of tasks doing the
+data preparation, the analysis, reporting results with tables and figures and, finally,
+tasks which compile the reports.
+
+Often, people keep all files in the workflow up-to-date by
+
+- executing all tasks by hand.
+
+  It is problematic because communicating the build process to collaborators is hard and
+  the process itself is error-prone since one might messes up the order or forgets to
+  run a task.
+
+- having a main file which runs all tasks.
+
+  The setup usually cannot infer which tasks need to be run. Thus, the build time is
+  unnecessarily high. Often times, the main file introduces side-effects into the tasks
+  via global variables or other mechanisms which makes it impossible to run tasks
+  independent from the main file. This is a nightmare if you need to debug your project.
+
+A build system is a framework to manage tasks and dependencies and, at best, the user
+does not even feel the layer between her and the tasks.
+
+From the research perspective, a build system is especially useful because it enables or
+facilitates the reproducibility of projects. For users who are not programmers by
+nature, it is necessary that the interface of the build system is intuitive and has a
+steep learning curve which are both goals pytask tries to accomplish.
+
+From a software engineering perspective, a build system helps to modularize your code.
+Modularization means to structure code into logical chunks and to reuse code. It reduces
+maintenance costs and facilitates testing. Without a build system, users might opt for
+larger chunks because a more granular structure is harder to keep in sync.

docs/explanations/index.rst

@@ -30,29 +30,29 @@ This is the documentation of pytask. You can install the package from `Anaconda.
     $ conda config --add channels conda-forge --add channels pytask
     $ conda install pytask
 
-The documentation has currently one of four planned parts.
+The documentation has four parts.
 
 .. raw:: html
 
     <div class="row">
         <div class="column">
             <a href="tutorials/index.html" id="index-link">
                 <div class="card">
-                    <img src="_static/images/light-bulb.svg" class="card-img-top"
+                    <img src="_static/images/light-bulb.svg"
                          alt="tutorials-icon" height="52"
                     >
                     <h5>Tutorials</h5>
                     <p>
-                        Tutorials help you to get started. If you do not know
-                        what a build system or pytask is, start here.
+                        Tutorials help you to get started with pytask, explain the
+                        interface and basic capabilities.
                     </p>
                 </div>
             </a>
         </div>
         <div class="column">
             <a href="how_to_guides/index.html" id="index-link">
                 <div class="card">
-                    <img src="_static/images/book.svg" class="card-img-top"
+                    <img src="_static/images/book.svg"
                          alt="how-to guides icon" height="52"
                     >
                     <h5>How-to Guides</h5>
@@ -66,12 +66,12 @@ The documentation has currently one of four planned parts.
         <div class="column">
             <a href="explanations/index.html" id="index-link">
                 <div class="card">
-                    <img src="_static/images/books.svg" class="card-img-top"
+                    <img src="_static/images/books.svg"
                          alt="explanations icon" height="52"
                     >
                     <h5>Explanations</h5>
                     <p>
-                        Explanations give detailed information to key topics and
+                        Explanations give detailed information on key topics and
                         concepts which underlie the package.
                     </p>
                 </div>
@@ -80,12 +80,12 @@ The documentation has currently one of four planned parts.
         <div class="column">
             <a href="reference_guides/index.html" id="index-link">
                 <div class="card">
-                    <img src="_static/images/coding.svg" class="card-img-top"
+                    <img src="_static/images/coding.svg"
                          alt="reference guides icon" height="52"
                     >
                     <h5>Reference Guides</h5>
                     <p>
-                        Reference Guides explain the implementation and provide an
+                        Reference guides explain the implementation and provide an
                         entry-point for developers.
                     </p>
                 </div>

docs/explanations/why_do_i_need_a_build_system.rst

@@ -31,7 +31,7 @@ General
 Command Line Interface
 ----------------------
 
-.. autofunction:: pytask_add_parameters_to_cli
+.. autofunction:: pytask_extend_command_line_interface
    :noindex: