Add more svgs and improve the documentation. (#256)

Author: tobiasraabe

.pre-commit-config.yaml

@@ -67,15 +67,39 @@ repos:
             pydocstyle,
             Pygments,
         ]
--   repo: https://github.com/PyCQA/doc8
-    rev: 0.11.1
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
     hooks:
-    -   id: doc8
--   repo: https://github.com/asottile/blacken-docs
-    rev: v1.12.1
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-gfm,
+            mdformat-black,
+        ]
+        args: [--wrap, "88"]
+        files: (README\.md)
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
     hooks:
-    -   id: blacken-docs
-        additional_dependencies: [black==22.3.0]
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-myst,
+            mdformat-black,
+        ]
+        args: [--wrap, "88"]
+        files: (docs/.)
+        exclude: |
+            (?x)^(
+                docs/source/how_to_guides/bp_structure_of_task_files.md|
+                docs/source/how_to_guides/how_to_influence_build_order.md|
+                docs/source/how_to_guides/repeating_tasks_with_different_inputs_the_pytest_way.md|
+                docs/source/reference_guides/hookspecs.md|
+                docs/source/tutorials/configuration.md|
+                docs/source/tutorials/defining_dependencies_products.md|
+                docs/source/tutorials/making_tasks_persist.md|
+                docs/source/tutorials/repeating_tasks_with_different_inputs.md|
+                docs/source/tutorials/selecting_tasks.md|
+                docs/source/tutorials/set_up_a_project.md
+            )$
 -   repo: https://github.com/econchick/interrogate
     rev: 1.5.0
     hooks:

README.md

@@ -4,7 +4,7 @@
     </p>
 </a>
 
-------------------------------------------------------------------------
+______________________________________________________________________
 
 <!-- Keep in sync with docs/source/index.md -->
 
@@ -15,40 +15,35 @@
 [![PyPI - License](https://img.shields.io/pypi/l/pytask)](https://pypi.org/project/pytask)
 [![image](https://readthedocs.org/projects/pytask-dev/badge/?version=latest)](https://pytask-dev.readthedocs.io/en/stable)
 [![image](https://img.shields.io/github/workflow/status/pytask-dev/pytask/main/main)](https://github.com/pytask-dev/pytask/actions?query=branch%3Amain)
-[![image](https://codecov.io/gh/pytask-dev/pytask/branch/main/graph/badge.svg)](https://codecov.io/gh/pytask-dev/pytask)
+[![image](https://codecov.io/gh/pytask-dev/pytask/branch/main/graph/badge.svg)](https://app.codecov.io/gh/pytask-dev/pytask)
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/pytask-dev/pytask/main.svg)](https://results.pre-commit.ci/latest/github/pytask-dev/pytask/main)
 [![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 <!-- Keep in sync with docs/source/index.md -->
 
-In its highest aspirations, pytask tries to be pytest as a build system. It\'s main
-purpose is to facilitate reproducible research by automating workflows in research
-projects. Its features include:
+pytask is a workflow management system which facilitates reproducible data analyses. Its
+features include:
 
 - **Automatic discovery of tasks.**
 - **Lazy evaluation.** If a task, its dependencies, and its products have not changed,
   do not execute it.
-- **Debug mode.** [Jump into the
-  debugger](https://pytask-dev.readthedocs.io/en/stable/tutorials/how_to_debug.html) if
-  a task fails, get feedback quickly, and be more productive.
-- **Repeat a task with different inputs.** [Loop over task
-  functions](https://pytask-dev.readthedocs.io/en/stable/tutorials/repeating_tasks_with_different_inputs.html)
+- **Debug mode.**
+  [Jump into the debugger](https://pytask-dev.readthedocs.io/en/stable/tutorials/debugging.html)
+  if a task fails, get feedback quickly, and be more productive.
+- **Repeat a task with different inputs.**
+  [Loop over task functions](https://pytask-dev.readthedocs.io/en/stable/tutorials/repeating_tasks_with_different_inputs.html)
   to run the same task with different inputs.
-- **Select tasks via expressions.** Run only a subset of tasks with [expressions and
-  marker
-  expressions](https://pytask-dev.readthedocs.io/en/stable/tutorials/selecting_tasks.html)
-  known from pytest.
+- **Select tasks via expressions.** Run only a subset of tasks with
+  [expressions and marker expressions](https://pytask-dev.readthedocs.io/en/stable/tutorials/selecting_tasks.html).
 - **Easily extensible with plugins**. pytask is built on top of
   [pluggy](https://pluggy.readthedocs.io/en/latest/), a plugin management framework,
   which allows you to adjust pytask to your needs. Plugins are available for
   [parallelization](https://github.com/pytask-dev/pytask-parallel),
   [LaTeX](https://github.com/pytask-dev/pytask-latex),
   [R](https://github.com/pytask-dev/pytask-r), and
   [Stata](https://github.com/pytask-dev/pytask-stata) and more can be found
-  [here](https://github.com/topics/pytask). Read in [this
-  tutorial](https://pytask-dev.readthedocs.io/en/stable/tutorials/how_to_use_plugins.html)
-  how to use and create plugins with a
-  [cookiecutter](https://github.com/pytask-dev/cookiecutter-pytask-plugin).
+  [here](https://github.com/topics/pytask). Learn more about plungins in
+  [this tutorial](https://pytask-dev.readthedocs.io/en/stable/tutorials/plugins.html).
 
 # Installation
 
@@ -73,8 +68,8 @@ installed via the [Microsoft Store](https://aka.ms/terminal).
 
 To quickly set up a new project, use the
 [cookiecutter-pytask-project](https://github.com/pytask-dev/cookiecutter-pytask-project)
-template or start from [other templates or example
-projects](https://pytask-dev.readthedocs.io/en/stable/how_to_guides/bp_templates_and_projects.html).
+template or start from
+[other templates or example projects](https://pytask-dev.readthedocs.io/en/stable/how_to_guides/bp_templates_and_projects.html).
 
 # Usage
 
@@ -94,13 +89,12 @@ def task_hello_earth(produces):
 
 Here are some details:
 
--   Dependencies and products of a task are tracked via markers. For dependencies use
-    `@pytask.mark.depends_on` and for products use `@pytask.mark.produces`. Use strings
-    and `pathlib.Path` to specify the location. Pass multiple dependencies or products
-    as a list or a dictionary for positional or key-based access.
--   With `produces` (and `depends_on`) as function arguments, you get access to the
-    dependencies and products inside the function via `pathlib.Path` objects. Here,
-    `produces` holds the path to `"hello_earth.txt"`.
+- Dependencies and products of a task are tracked via markers. For dependencies use
+  `@pytask.mark.depends_on` and for products use `@pytask.mark.produces`. Use strings
+  and `pathlib.Path` to specify the location.
+- Use `produces` (and `depends_on`) as function arguments to access the paths of the
+  dependencies and products inside the function. All values are converted to
+  `pathlib.Path`'s. Here, `produces` holds the path to `"hello_earth.txt"`.
 
 To execute the task, enter `pytask` on the command-line
 
@@ -110,8 +104,8 @@ To execute the task, enter `pytask` on the command-line
 
 The documentation can be found under <https://pytask-dev.readthedocs.io/en/stable> with
 [tutorials](https://pytask-dev.readthedocs.io/en/stable/tutorials/index.html) and guides
-for [best
-practices](https://pytask-dev.readthedocs.io/en/stable/how_to_guides/index.html).
+for
+[best practices](https://pytask-dev.readthedocs.io/en/stable/how_to_guides/index.html).
 
 # Changes
 
@@ -124,10 +118,19 @@ pytask is distributed under the terms of the [MIT license](LICENSE).
 
 # Acknowledgment
 
-The license also includes a copyright and permission notice from pytest since some
-modules, classes, and functions are copied from pytest. Not to mention how pytest has
-inspired the development of pytask in general. Without the amazing work of Holger Krekel
-and pytest\'s many contributors, this project would not have been possible. Thank you!
+The license also includes a copyright and permission notice from
+[pytest](https://github.com/pytest-dev/pytest) since some modules, classes, and
+functions are copied from pytest. Not to mention how pytest has inspired the development
+of pytask in general. Without the amazing work of
+[Holger Krekel](https://github.com/hpk42) and pytest's many contributors, this project
+would not have been possible. Thank you!
+
+pytask ows its beautiful appearance on the command line to
+[rich](https://github.com/Textualize/rich) written by
+[Will McGugan](https://github.com/willmcgugan).
+
+Repeating tasks in loops is inspired by [ward](https://github.com/darrenburns/ward)
+written by [Darren Burns](https://github.com/darrenburns).
 
 # Citation
 

docs/rtd_environment.yml

@@ -3,7 +3,7 @@ channels:
   - nodefaults
 
 dependencies:
-  - python >= 3.7
+  - python >=3.7
   - pip
   - setuptools_scm
   - toml
@@ -14,7 +14,6 @@ dependencies:
   - nbsphinx
   - myst-parser
   - sphinx
-  - sphinx-autoapi
   - sphinx-click
   - sphinx-copybutton
   - sphinx-panels