Some changes to the docs. (#538)

Author: tobiasraabe

.pre-commit-config.yaml

@@ -76,8 +76,8 @@ repos:
         additional_dependencies: [
             mdformat-gfm,
             mdformat-black,
+            mdformat-pyproject,
         ]
-        args: [--wrap, "88"]
         files: (README\.md)
 -   repo: https://github.com/executablebooks/mdformat
     rev: 0.7.17
@@ -86,31 +86,9 @@ repos:
         additional_dependencies: [
             mdformat-myst,
             mdformat-black,
+            mdformat-pyproject,
         ]
-        args: [--wrap, "88"]
         files: (docs/.)
-        exclude: |
-            (?x)^(
-                docs/source/index.md|
-                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/migrating_from_scripts_to_pytask.md|
-                docs/source/how_to_guides/repeating_tasks_with_different_inputs_the_pytest_way.md|
-                docs/source/how_to_guides/using_task_returns.md|
-                docs/source/how_to_guides/writing_custom_nodes.md|
-                docs/source/how_to_guides/hashing_inputs_of_tasks.md|
-                docs/source/how_to_guides/remote_files.md|
-                docs/source/reference_guides/hookspecs.md|
-                docs/source/tutorials/configuration.md|
-                docs/source/tutorials/debugging.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|
-                docs/source/tutorials/using_a_data_catalog.md|
-                docs/source/tutorials/write_a_task.md
-            )$
 -   repo: https://github.com/nbQA-dev/nbQA
     rev: 1.7.1
     hooks:

docs/source/changes.md

@@ -23,6 +23,8 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
 - {pull}`528` improves the codecov setup and coverage.
 - {pull}`535` reenables and fixes tests with Jupyter.
 - {pull}`536` allows partialed functions to be task functions.
+- {pull}`538` updates the documentation. For example, colon fences are replaced by
+  backticks to allow formatting all pages by mdformat.
 - {pull}`539` implements the {confval}`hook_module` configuration value and
   `--hook-module` commandline option to register hooks.
 - {pull}`540` changes the CLI entry-point and allow `pytask.build(tasks=task_func)` as
@@ -124,7 +126,7 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
 - {pull}`413` removes scripts to generate `.svg`s.
 - {pull}`414` allow more ruff rules.
 - {pull}`416` removes `.from_annot` again.
-- {pull}`417` deprecates {func}`pytask.mark.task` in favor of {func}`pytask.task`.
+- {pull}`417` deprecates `pytask.mark.task` in favor of {func}`pytask.task`.
 - {pull}`418` fixes and error and simplifies code in `dag.py`.
 - {pull}`420` converts `DeprecationWarning`s to `FutureWarning`s for the deprecated
   decorators.
@@ -170,7 +172,7 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
 - {pull}`376` enhances the documentation for `pytask dag`.
 - {pull}`378` conditionally skips test on MacOS.
 - {pull}`381` deprecates `@pytask.mark.parametrize`. (Closes {issue}`233`.)
-- {pull}`501` removes {class}`pytask.MetaNode`.
+- {pull}`501` removes `pytask.MetaNode`.
 
 ## 0.3.1 - 2023-12-25
 
@@ -254,7 +256,7 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
   arguments. It also implements {class}`_pytask.models.CollectionMetadata` to carry
   parametrized arguments to the task class.
 - {pull}`228` removes `task.pytaskmark` and moves the information to
-  {attr}`_pytask.models.CollectionMetadata.markers`.
+  {attr}`pytask.CollectionMetadata.markers`.
 - {pull}`229` implements a new loop-based approach to parametrizations using the
   {func}`@pytask.mark.task <pytask.mark.task>` decorator.
 - {pull}`230` implements {class}`_pytask.logging._TimeUnit` as a
@@ -337,8 +339,8 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
   the direction of the DAG.
 - {pull}`186` enhance live displays by deactivating auto-refresh, among other things.
 - {pull}`187` allows to enable and disable showing tracebacks and potentially different
-  styles in the future with {confval}`show_traceback=True|False`.
-- {pull}`188` refactors some code related to {class}`_pytask.enums.ExitCode`.
+  styles in the future with `show_traceback=True|False`.
+- {pull}`188` refactors some code related to {class}`pytask.ExitCode`.
 - {pull}`189` do not display a table in the execution if no task was run.
 - {pull}`190` updates the release notes.
 
@@ -389,8 +391,8 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
 
 ## 0.1.1 - 2021-08-25
 
-- {pull}`138` changes the default {confval}`verbosity` to `1` which displays the live
-  table during execution and `0` display the symbols for outcomes (e.g. `.`, `F`, `s`).
+- {pull}`138` changes the default `verbosity` to `1` which displays the live table
+  during execution and `0` display the symbols for outcomes (e.g. `.`, `F`, `s`).
 - {pull}`139` enables rich's auto-refresh mechanism for live objects which causes almost
   no performance penalty for the live table compared to the symbolic output.
 

docs/source/conf.py

@@ -85,14 +85,16 @@
     "click": ("https://click.palletsprojects.com/en/8.0.x/", None),
     "deepdiff": ("https://zepworks.com/deepdiff/current/", None),
     "networkx": ("https://networkx.org/documentation/stable", None),
+    "nx": ("https://networkx.org/documentation/stable", None),
     "pandas": ("https://pandas.pydata.org/docs", None),
+    "pd": ("https://pandas.pydata.org/docs", None),
     "pluggy": ("https://pluggy.readthedocs.io/en/latest", None),
     "pygraphviz": ("https://pygraphviz.github.io/documentation/stable/", None),
     "python": ("https://docs.python.org/3.10", None),
 }
 
 # MyST
-myst_enable_extensions = ["colon_fence", "deflist", "dollarmath"]
+myst_enable_extensions = ["deflist", "dollarmath"]
 myst_footnote_transition = False
 
 # Open Graph

docs/source/how_to_guides/bp_structure_of_task_files.md

@@ -13,9 +13,9 @@ are looking for orientation or inspiration, here are some tips.
 - Task functions should be at the top of a task module to easily identify what the
   module is for.
 
-  :::{seealso}
+  ```{seealso}
   The only exception might be for {doc}`repetitions <bp_scaling_tasks>`.
-  :::
+  ```
 
 - The purpose of the task function is to handle IO operations like loading and saving
   files and calling Python functions on the task's inputs. IO should not be handled in
@@ -44,11 +44,11 @@ module are re-run. If the runtime of all tasks in the module is high, you wait l
 for your tasks to finish or until an error occurs which prolongs your feedback loops and
 hurts your productivity.
 
-:::{seealso}
+```{seealso}
 Use {func}`@pytask.mark.persist <pytask.mark.persist>` if you want to avoid accidentally
 triggering an expensive task. It is also explained in [this
 tutorial](../tutorials/making_tasks_persist).
-:::
+```
 
 ### Structure of the module
 
@@ -86,11 +86,11 @@ Here is an example of a task module which conforms to all advices.
 ```{literalinclude} ../../../docs_src/how_to_guides/bp_structure_of_task_files.py
 ```
 
-:::{seealso}
+```{seealso}
 The structure of the task module is greatly inspired by John Ousterhout's "A Philosopy
 of Software Design" in which he coins the name "deep modules". In short, deep modules
 have simple interfaces which are defined by one or a few {term}`public functions <public
 function>` (or classes) which provide the functionality. The complexity is hidden inside
 the module in {term}`private functions <private function>` which are called by the
 {term}`public functions <public function>`.
-:::
+```

docs/source/how_to_guides/hashing_inputs_of_tasks.md

@@ -11,15 +11,15 @@ If an input is not parsed by any more specific node type, the general
 In the following example, the argument `text` will be parsed as a
 {class}`~pytask.PythonNode`.
 
-:::::{tab-set}
+`````{tab-set}
 
-::::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 
 ```{literalinclude} ../../../docs_src/how_to_guides/hashing_inputs_of_tasks_example_1_py310.py
 ```
 
-::::
-:::::
+````
+`````
 
 By default, pytask does not detect changes in {class}`~pytask.PythonNode` and if the
 value would change (without changing the task module), pytask would not rerun the task.
@@ -28,15 +28,15 @@ We can also hash the value of {class}`~pytask.PythonNode` s so that pytask knows
 the input changed. For that, we need to use the {class}`~pytask.PythonNode` explicitly
 and set `hash = True`.
 
-:::::{tab-set}
+`````{tab-set}
 
-::::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 
 ```{literalinclude} ../../../docs_src/how_to_guides/hashing_inputs_of_tasks_example_2_py310.py
 ```
 
-::::
-:::::
+````
+`````
 
 When `hash=True`, pytask will call the builtin {func}`hash` on the input that will call
 the `__hash__()` method of the object.
@@ -62,10 +62,10 @@ from interpreter session to interpreter session for security reasons (see
 ```
 
 {class}`list` and {class}`dict` are not hashable by default. Luckily, there are
-libraries who provide this functionality like {mod}`deepdiff`. We can use them to pass a
+libraries who provide this functionality like `deepdiff`. We can use them to pass a
 function to the {class}`~pytask.PythonNode` that generates a stable hash.
 
-First, install {mod}`deepdiff`.
+First, install `deepdiff`.
 
 ```console
 $ pip install deepdiff
@@ -74,12 +74,12 @@ $ conda install deepdiff
 
 Then, create the hash function and pass it to the node.
 
-:::::{tab-set}
+`````{tab-set}
 
-::::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 
 ```{literalinclude} ../../../docs_src/how_to_guides/hashing_inputs_of_tasks_example_3_py310.py
 ```
 
-::::
-:::::
+````
+`````

docs/source/how_to_guides/how_to_influence_build_order.md

@@ -1,23 +1,23 @@
 # How to influence the build order
 
-:::{important}
+```{important}
 This guide shows how to influence the order in which tasks are executed. The feature
 should be treated with caution since it might make projects work whose dependencies and
 products are not fully specified.
-:::
+```
 
 You can influence the order in which tasks are executed by assigning preferences to
 tasks. Use {func}`@pytask.mark.try_first <pytask.mark.try_first>` to execute a task as
 early as possible and {func}`@pytask.mark.try_last <pytask.mark.try_last>` to defer
 execution.
 
-:::{note}
+```{note}
 A little bit more background: Tasks, dependencies and products form a directed acyclic
 graph (DAG). A [topological ordering](https://en.wikipedia.org/wiki/Topological_sorting)
 determines the order in which tasks are executed such that tasks are not run until their
 predecessors have been executed. You should not assume a fixed ordering in which tasks
 are executed.
-:::
+```
 
 As an example, here are two tasks where the decorator ensures that the output of the
 second task is always shown before the output of the first task.

docs/source/how_to_guides/migrating_from_scripts_to_pytask.md

@@ -55,7 +55,7 @@ An `if __name__ == "__main__"` block must be deleted.
 To let pytask know the order in which to execute tasks and when to re-run them, you'll
 need to specify task dependencies and products. Add dependencies as arguments to the
 function with default values. Do the same for products, but also add the special
-{obj}`~pytask.Product` annotation with {obj}`Annotated[Path, Product]`. For example:
+{obj}`~pytask.Product` annotation with `Annotated[Path, Product]`. For example:
 
 ```{literalinclude} ../../../docs_src/how_to_guides/migrating_from_scripts_to_pytask_4.py
 ```
@@ -65,10 +65,10 @@ You can also use a dictionary to group multiple dependencies or products.
 ```{literalinclude} ../../../docs_src/how_to_guides/migrating_from_scripts_to_pytask_5.py
 ```
 
-:::{seealso}
+```{seealso}
 If you want to learn more about dependencies and products, read the
 [tutorial](../tutorials/defining_dependencies_products.md).
-:::
+```
 
 ## Execution
 
@@ -88,10 +88,10 @@ then automatically spawn multiple processes to run the workflow in parallel.
 $ pytask -n 4
 ```
 
-:::{seealso}
+```{seealso}
 You can find more information on pytask-parallel in the
 [readme](https://github.com/pytask-dev/pytask-parallel) on Github.
-:::
+```
 
 ## Bonus: From R script to task
 
@@ -109,10 +109,10 @@ $ pip install pytask-r
 $ conda install -c conda-forge pytask-r
 ```
 
-:::{seealso}
+```{seealso}
 Checkout [pytask-julia](https://github.com/pytask-dev/pytask-julia) and
 [pytask-stata](https://github.com/pytask-dev/pytask-stata), too!
-:::
+```
 
 And here is the R script `prepare_data.r` that we want to integrate.
 
@@ -131,8 +131,8 @@ products.
 ```{literalinclude} ../../../docs_src/how_to_guides/migrating_from_scripts_to_pytask_6.py
 ```
 
-pytask automatically makes the paths to the dependencies and products available to the
-R file via a JSON file. Let us amend the R script to load the information from the JSON
+pytask automatically makes the paths to the dependencies and products available to the R
+file via a JSON file. Let us amend the R script to load the information from the JSON
 file.
 
 ```r

docs/source/how_to_guides/remote_files.md

@@ -12,11 +12,11 @@ with remote files. The package provides a {mod}`pathlib`-like interface, making
 easy to interact with files from an HTTP(S)-, Dropbox-, S3-, GCP-, Azure-based
 filesystem, and many more.
 
-:::{warning}
+```{warning}
 universal_pathlib does currently not support Python 3.12. To track progress, see [this
 PR](https://github.com/fsspec/universal_pathlib/pull/152) and check the [releases
 `>0.1.4`](https://github.com/fsspec/universal_pathlib/releases)
-:::
+```
 
 ## HTTP(S)-based filesystem
 
@@ -63,11 +63,10 @@ After installing s3fs, rerun the command.
 ```
 
 Usually, you will need credentials to access files. Search in
-[fsspec's documentation](https://filesystem-spec.readthedocs.io/en/latest)
-or the plugin's documentation, here
-[s3fs](https://s3fs.readthedocs.io/en/latest/#credentials), for information on
-authentication. One way would be to set the environment variables `AWS_ACCESS_KEY_ID`
-and `AWS_SECRET_ACCESS_KEY`.
+[fsspec's documentation](https://filesystem-spec.readthedocs.io/en/latest) or the
+plugin's documentation, here [s3fs](https://s3fs.readthedocs.io/en/latest/#credentials),
+for information on authentication. One way would be to set the environment variables
+`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
 
 ## Detecting changes in remote files
 

docs/source/how_to_guides/using_task_returns.md

@@ -16,32 +16,32 @@ One way to declare the returns of functions as products is annotating the return
 In the following example, the second value of {class}`typing.Annotated` is a path that
 defines where the return of the function, a string, should be stored.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/using_task_returns_example_1_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/using_task_returns_example_1_py38.py
 ```
 
-:::
-::::
+````
+`````
 
 It works because internally the path is converted to a {class}`pytask.PathNode` that is
 able to store objects of type {class}`str` and {class}`bytes`.
 
-:::{seealso}
+```{seealso}
 Read the explanation on {doc}`nodes <../how_to_guides/writing_custom_nodes>` to learn
 more about how nodes work.
-:::
+```
 
 ## Task decorator
 
@@ -58,31 +58,31 @@ If a task function has multiple returns, you can use multiple nodes to store eac
 returns in a different place. The following example shows how to accomplish it with both
 of the previous interfaces.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/using_task_returns_example_3_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/using_task_returns_example_3_py38.py
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`@pytask.task`
+````{tab-item} @pytask.task
 
 ```{literalinclude} ../../../docs_src/how_to_guides/using_task_returns_example_3_task.py
 ```
 
-:::
-::::
+````
+`````
 
 Each return is mapped to its node by respecting its position in the tuple.
 
@@ -93,35 +93,35 @@ is a shallower tree.
 The following example shows how a task function with a complex structure of returns is
 mapped to the defined nodes.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/using_task_returns_example_4_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/using_task_returns_example_4_py38.py
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`@pytask.task`
+````{tab-item} @pytask.task
 
 ```{literalinclude} ../../../docs_src/how_to_guides/using_task_returns_example_4_task.py
 ```
 
-:::
-::::
+````
+`````
 
 The returns are mapped to the nodes as follows.
 
-```python
+```text
 PythonNode(name="dict1") <- "a"
 PythonNode(name="dict2") <- {"b": 1, "c": 2}
 PythonNode(name="tuple1") <- 3

docs/source/how_to_guides/writing_custom_nodes.md

@@ -17,47 +17,47 @@ to inputs and outputs and call {func}`~pandas.read_pickle` and
 ```{literalinclude} ../../../docs_src/how_to_guides/writing_custom_nodes_example_1.py
 ```
 
-To remove IO operations from the task and delegate them to pytask, we will write a
-`PickleNode` that automatically loads and stores Python objects.
+To remove IO operations from the task and delegate them to pytask, we will replicate the
+{class}`~pytask.PickleNode` that automatically loads and stores Python objects.
 
 And we pass the value to `df` via {obj}`~typing.Annotated` to preserve the type hint.
 
 The result will be the following task.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/writing_custom_nodes_example_2_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.10+ & Return
+````{tab-item} Python 3.10+ & Return
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/writing_custom_nodes_example_2_py310_return.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/writing_custom_nodes_example_2_py38.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+ & Return
+````{tab-item} Python 3.8+ & Return
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/writing_custom_nodes_example_2_py38_return.py
 ```
 
-:::
-::::
+````
+`````
 
 ## Nodes
 
@@ -73,54 +73,61 @@ follow at least the protocol {class}`~pytask.PNode` or, even better,
 
 ## `PickleNode`
 
-Since our {class}`PickleNode` will only vary slightly from {class}`~pytask.PathNode`, we
-use it as a template, and with some minor modifications, we arrive at the following
-class.
+Since our {class}`~pytask.PickleNode` will only vary slightly from
+{class}`~pytask.PathNode`, we use it as a template, and with some minor modifications,
+we arrive at the following class.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/writing_custom_nodes_example_3_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/how_to_guides/writing_custom_nodes_example_3_py38.py
 ```
 
-:::
-::::
+````
+`````
 
 Here are some explanations.
 
 - The node does not need to inherit from the protocol {class}`~pytask.PPathNode`, but
   you can do it to be more explicit.
+
 - The node has two attributes
+
   - `name` identifies the node in the DAG, so the name must be unique.
   - `path` holds the path to the file and identifies the node as a path node that is
     handled slightly differently than normal nodes within pytask.
+
 - The node has an additional property that computes the signature of the node. The
   signature is a hash and a unique identifier for the node. For most nodes it will be a
   hash of the path or the name.
-- The {func}`classmethod` {meth}`PickleNode.from_path` is a convenient method to
+
+- The {func}`classmethod` {meth}`~pytask.PickleNode.from_path` is a convenient method to
   instantiate the class.
-- The method {meth}`PickleNode.state` yields a value that signals the node's state. If
-  the value changes, pytask knows it needs to regenerate the workflow. We can use
-  the timestamp of when the node was last modified.
-- pytask calls {meth}`PickleNode.load` when it collects the values of function arguments
-  to run the function. The argument `is_product` signals that the node is loaded as a
-  product with a {class}`~pytask.Product` annotation or via `produces`.
+
+- The method {meth}`~pytask.PickleNode.state` yields a value that signals the node's
+  state. If the value changes, pytask knows it needs to regenerate the workflow. We can
+  use the timestamp of when the node was last modified.
+
+- pytask calls {meth}`~pytask.PickleNode.load` when it collects the values of function
+  arguments to run the function. The argument `is_product` signals that the node is
+  loaded as a product with a {class}`~pytask.Product` annotation or via `produces`.
 
   When the node is loaded as a dependency, we want to inject the value of the pickle
   file. In the other case, the node returns itself so users can call
-  {meth}`PickleNode.save` themselves.
-- {meth}`PickleNode.save` is called when a task function returns and allows to save the
-  return values.
+  {meth}`~pytask.PickleNode.save` themselves.
+
+- {meth}`~pytask.PickleNode.save` is called when a task function returns and allows to
+  save the return values.
 
 ## Conclusion
 
@@ -135,14 +142,12 @@ databases. [^kedro]
 
 ## References
 
-[^structural-subtyping]:
-    Structural subtyping is similar to ABCs an approach in Python to
-    enforce interfaces, but it can be considered more pythonic since it is closer to
-    duck typing. Hynek Schlawack wrote a comprehensive
+[^structural-subtyping]: Structural subtyping is similar to ABCs an approach in Python to enforce interfaces, but
+    it can be considered more pythonic since it is closer to duck typing. Hynek Schlawack
+    wrote a comprehensive
     [guide on subclassing](https://hynek.me/articles/python-subclassing-redux/) that
     features protocols under "Type 2". Glyph wrote an introduction to protocols called
     [I want a new duck](https://glyph.twistedmatrix.com/2020/07/new-duck.html).
 
-[^kedro]:
-    Kedro, another workflow system, provides many adapters to data sources:
+[^kedro]: Kedro, another workflow system, provides many adapters to data sources:
     https://docs.kedro.org/en/stable/kedro_datasets.html.

docs/source/index.md

@@ -49,10 +49,11 @@ there.
 
 If you want to know more about pytask, dive into one of the following topics
 
-::::{grid} 1 2 2 2
-:gutter: 3
-
-:::{grid-item-card}
+`````{grid} 1 2 2 2
+---
+gutter: 3
+---
+````{grid-item-card}
 :text-align: center
 :img-top: _static/images/light-bulb.svg
 :class-img-top: index-card-image
@@ -69,9 +70,9 @@ Tutorials
 
 Tutorials help you to get started with pytask and how you manage your first project.
 
-:::
+````
 
-:::{grid-item-card}
+````{grid-item-card}
 :text-align: center
 :img-top: _static/images/book.svg
 :class-img-top: index-card-image
@@ -89,9 +90,9 @@ How-to Guides
 How-to guides provide instructions for very specific and advanced tasks and document
 best-practices.
 
-:::
+````
 
-:::{grid-item-card}
+````{grid-item-card}
 :text-align: center
 :img-top: _static/images/books.svg
 :class-img-top: index-card-image
@@ -108,9 +109,9 @@ Explanations
 
 Explanations deal with key topics and concepts which underlie the package.
 
-:::
+````
 
-:::{grid-item-card}
+````{grid-item-card}
 :text-align: center
 :img-top: _static/images/coding.svg
 :class-img-top: index-card-image
@@ -127,9 +128,9 @@ Reference Guides
 
 Reference guides explain the implementation and provide an entry-point for developers.
 
-:::
+````
 
-::::
+`````
 
 ```{toctree}
 ---

docs/source/reference_guides/api.md

@@ -28,6 +28,39 @@ To write to the terminal, use pytask's console.
 .. class:: pytask.console
 ```
 
+## Exceptions
+
+Exceptions all inherit from
+
+```{eval-rst}
+.. autoclass:: pytask.PytaskError
+```
+
+The following exceptions can be used to interrupt pytask's flow, emit reduced tracebacks
+and return the correct exit codes.
+
+```{eval-rst}
+.. autoclass:: pytask.CollectionError
+.. autoclass:: pytask.ConfigurationError
+.. autoclass:: pytask.ExecutionError
+.. autoclass:: pytask.ResolvingDependenciesError
+```
+
+The remaining exceptions convey specific errors.
+
+```{eval-rst}
+.. autoclass:: pytask.NodeNotCollectedError
+.. autoclass:: pytask.NodeNotFoundError
+```
+
+## General classes
+
+```{eval-rst}
+.. autoclass:: pytask.Session
+.. autoclass:: pytask.DataCatalog
+   :members:
+```
+
 ## Marks
 
 pytask uses marks to attach additional information to task functions which is processed
@@ -45,15 +78,11 @@ by the host or by plugins. The following marks are available by default.
         Can be any valid Python object or an iterable of any Python objects. To be
         valid, it must be parsed by some hook implementation for the
         :func:`_pytask.hookspecs.pytask_collect_node` entry-point.
-```
 
-```{eval-rst}
 .. function:: pytask.mark.persist()
 
     A marker for a task which should be persisted.
-```
 
-```{eval-rst}
 .. function:: pytask.mark.produces(objects: Any | Iterable[Any] | dict[Any, Any])
 
     Specify products of a task.
@@ -63,40 +92,30 @@ by the host or by plugins. The following marks are available by default.
         Can be any valid Python object or an iterable of any Python objects. To be
         valid, it must be parsed by some hook implementation for the
         :func:`_pytask.hookspecs.pytask_collect_node` entry-point.
-```
 
-```{eval-rst}
 .. function:: pytask.mark.skipif(condition: bool, *, reason: str)
 
     Skip a task based on a condition and provide a necessary reason.
 
     :param bool condition: A condition for when the task is skipped.
     :param str reason: A reason why the task is skipped.
-```
 
-```{eval-rst}
 .. function:: pytask.mark.skip_ancestor_failed(reason: str = "No reason provided")
 
     An internal marker for a task which is skipped because an ancestor failed.
 
     :param str reason: A reason why the task is skipped.
-```
 
-```{eval-rst}
 .. function:: pytask.mark.skip_unchanged()
 
     An internal marker for a task which is skipped because nothing has changed.
 
     :param str reason: A reason why the task is skipped.
-```
 
-```{eval-rst}
 .. function:: pytask.mark.skip()
 
     Skip a task.
-```
 
-```{eval-rst}
 .. function:: pytask.mark.task(name, *, id, kwargs)
 
     The task decorator allows to mark any task function regardless of its name as a task
@@ -118,9 +137,6 @@ by the host or by plugins. The following marks are available by default.
         A dictionary containing keyword arguments which are passed to the task when it
         is executed.
 
-```
-
-```{eval-rst}
 .. function:: pytask.mark.try_first
 
     Indicate that the task should be executed as soon as possible.
@@ -136,9 +152,6 @@ by the host or by plugins. The following marks are available by default.
         dependencies and products and automatic inference may be incomplete like with
         pytask-latex and latex-dependency-scanner.
 
-```
-
-```{eval-rst}
 .. function:: pytask.mark.try_last
 
     Indicate that the task should be executed as late as possible.
@@ -207,39 +220,6 @@ These functions help you to handle marks.
 .. autofunction:: pytask.set_marks
 ```
 
-## Exceptions
-
-Exceptions all inherit from
-
-```{eval-rst}
-.. autoclass:: pytask.PytaskError
-```
-
-The following exceptions can be used to interrupt pytask's flow, emit reduced tracebacks
-and return the correct exit codes.
-
-```{eval-rst}
-.. autoclass:: pytask.CollectionError
-.. autoclass:: pytask.ConfigurationError
-.. autoclass:: pytask.ExecutionError
-.. autoclass:: pytask.ResolvingDependenciesError
-```
-
-The remaining exceptions convey specific errors.
-
-```{eval-rst}
-.. autoclass:: pytask.NodeNotCollectedError
-.. autoclass:: pytask.NodeNotFoundError
-```
-
-## General classes
-
-```{eval-rst}
-.. autoclass:: pytask.Session
-.. autoclass:: pytask.DataCatalog
-   :members:
-```
-
 ## Protocols
 
 Protocols define how tasks and nodes for dependencies and products have to be set up.
@@ -261,11 +241,11 @@ Nodes are the interface for different kinds of dependencies or products.
 
 ```{eval-rst}
 .. autoclass:: pytask.PathNode
-   :members: load, save
+   :members:
 .. autoclass:: pytask.PickleNode
-   :members: load, save
+   :members:
 .. autoclass:: pytask.PythonNode
-   :members: load, save
+   :members:
 ```
 
 To parse dependencies and products from nodes, use the following functions.
@@ -301,6 +281,7 @@ attribute of the task function.
 
 ```{eval-rst}
 .. autoclass:: pytask.CollectionMetadata
+    :members:
 ```
 
 ## Outcomes
@@ -370,8 +351,12 @@ resolution and execution.
 ## Tree utilities
 
 ```{eval-rst}
-.. automodule:: pytask.tree_util
-    :members:
+.. autoclass:: pytask.tree_util.PyTree
+.. autofunction:: pytask.tree_util.tree_flatten_with_path
+.. autofunction:: pytask.tree_util.tree_leaves
+.. autofunction:: pytask.tree_util.tree_map
+.. autofunction:: pytask.tree_util.tree_map_with_path
+.. autofunction:: pytask.tree_util.tree_structure
 ```
 
 ## Typing
@@ -384,6 +369,7 @@ resolution and execution.
     >>> def task_example(path: Annotated[Path, Product]) -> None:
     ...     path.write_text("Hello, World!")
 
+.. autofunction:: pytask.is_task_function
 ```
 
 ## Tracebacks

docs/source/reference_guides/configuration.md

@@ -35,10 +35,10 @@ strongly discouraged, you can deactivate the warning in the configuration file w
 check_casing_of_paths = false
 ```
 
-:::{note}
+```{note}
 An error is only raised on Windows when a case-insensitive path is used. Contributions
 are welcome to also support macOS.
-:::
+```
 
 ````
 

docs/source/reference_guides/hookspecs.md

@@ -67,12 +67,12 @@ The following hooks traverse directories and collect tasks from files.
 The following hooks are designed to build a DAG from tasks and dependencies and check
 which files have changed and need to be re-run.
 
-:::{warning}
+```{warning}
 This step is still experimental and likely to change in the future. If you are planning
 to write a plugin which extends pytask in this dimension, please, start a discussion
 before writing a plugin. It may make your life easier if changes in pytask anticipate
 your plugin.
-:::
+```
 
 ```{eval-rst}
 .. autofunction:: pytask_dag

docs/source/tutorials/configuration.md

@@ -39,10 +39,10 @@ The second option is to let pytask try to find the configuration itself.
 
 1. Find the common base directory of all paths passed to pytask (default to the current
    working directory).
-2. Starting from this directory, look at all parent directories, and return the file if
+1. Starting from this directory, look at all parent directories, and return the file if
    it exists.
-3. Stop searching if a directory contains a `.git` directory/file or a valid configuration file with
-   the right section.
+1. Stop searching if a directory contains a `.git` directory/file or a valid
+   configuration file with the right section.
 
 ## The options
 

docs/source/tutorials/debugging.md

@@ -12,15 +12,15 @@ find out the cause of the exception.
 ```{include} ../_static/md/pdb.md
 ```
 
-:::{tip}
+```{tip}
 If you do not know about the Python debugger or pdb yet, check out this [explanation
 from RealPython](https://realpython.com/python-debugging-pdb/).
-:::
+```
 
-:::{note}
+```{note}
 A following tutorial explains {doc}`how to select a subset of tasks <selecting_tasks>`.
 Combine it with the {option}`pytask build --pdb` flag to debug specific tasks.
-:::
+```
 
 ## Tracing
 

docs/source/tutorials/defining_dependencies_products.md

@@ -11,15 +11,15 @@ You find a tutorial on type hints {doc}`here <../type_hints>`.
 
 If you want to avoid type annotations for now, look at the tab named `produces`.
 
-The `Decorators` tab documents the deprecated approach that should not be used
-anymore and will be removed in version v0.5.
+The `Decorators` tab documents the deprecated approach that should not be used anymore
+and will be removed in version v0.5.
 
 In this tutorial, we only deal with local files. If you want to use pytask with files
 online, S3, GCP, Azure, etc., read the
 {doc}`guide on remote files <../how_to_guides/remote_files>`.
 
-First, we focus on defining products that should already be familiar to you. Then,
-we focus on how you can declare task dependencies.
+First, we focus on defining products that should already be familiar to you. Then, we
+focus on how you can declare task dependencies.
 
 We use the same project as before and add a `task_plot_data.py` module.
 
@@ -47,9 +47,9 @@ my_project
 Let's revisit the task from the {doc}`previous tutorial <write_a_task>` that we defined
 in `task_data_preparation.py`.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_products_py310.py
@@ -59,9 +59,9 @@ in `task_data_preparation.py`.
 {class}`~pytask.Product` allows marking an argument as a product. After the
 task has finished, pytask will check whether the file exists.
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_products_py38.py
@@ -71,9 +71,9 @@ task has finished, pytask will check whether the file exists.
 {class}`~pytask.Product` allows marking an argument as a product. After the
 task has finished, pytask will check whether the file exists.
 
-:::
+````
 
-:::{tab-item} &#8203;`produces`
+````{tab-item} prodouces
 :sync: produces
 
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_products_produces.py
@@ -84,9 +84,9 @@ Tasks can use `produces` as a "magic" argument name. Every value, or in this cas
 passed to this argument is automatically treated as a task product. Here, we pass the
 path as the default argument.
 
-:::
+````
 
-:::{tab-item} Decorators
+````{tab-item} Decorators
 :sync: decorators
 
 ```{warning}
@@ -103,13 +103,15 @@ task. After the task has finished, pytask will check whether the file exists.
 Add `produces` as an argument of the task function to get access to the same path inside
 the task function.
 
-:::
-::::
+````
 
-:::{tip}
-If you do not know about {mod}`pathlib` check out [^id3] and [^id4]. The module is
-beneficial for handling paths conveniently and across platforms.
-:::
+`````
+
+```{tip}
+If you do not know about {mod}`pathlib` check out this guide by
+[RealPython](https://realpython.com/python-pathlib/). The module is beneficial for
+handling paths conveniently and across platforms.
+```
 
 ## Dependencies
 
@@ -119,24 +121,24 @@ To show how dependencies work, we extend our project with another task that plot
 data generated with `task_create_random_data`. The task is called `task_plot_data`, and
 we will define it in `task_plot_data.py`.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 To specify that the task relies on the data set `data.pkl`, you can add the path
 to the function signature while choosing any argument name, here `path_to_data`.
 
-pytask assumes that all function arguments that do not have a {class}`~pytask.`Product`
+pytask assumes that all function arguments that do not have a {class}`~pytask.Product`
 annotation are dependencies of the task.
 
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_dependencies_py310.py
 :emphasize-lines: 11
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 To specify that the task relies on the data set `data.pkl`, you can add the path
@@ -149,9 +151,9 @@ annotation are dependencies of the task.
 :emphasize-lines: 11
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`produces`
+````{tab-item} prodouces
 :sync: produces
 
 To specify that the task relies on the data set `data.pkl`, you can add the path to the
@@ -164,9 +166,9 @@ pytask assumes that all function arguments that are not passed to the argument
 :emphasize-lines: 9
 ```
 
-:::
+````
 
-:::{tab-item} Decorators
+````{tab-item} Decorators
 :sync: decorators
 
 ```{warning}
@@ -182,8 +184,8 @@ access the dependency path inside the function and load the data.
 :emphasize-lines: 9, 11
 ```
 
-:::
-::::
+````
+`````
 
 Now, let us execute the two paths.
 
@@ -195,36 +197,36 @@ Now, let us execute the two paths.
 Dependencies and products do not have to be absolute paths. If paths are relative, they
 are assumed to point to a location relative to the task module.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_relative_py310.py
 :emphasize-lines: 8
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_relative_py38.py
 :emphasize-lines: 8
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`produces`
+````{tab-item} prodouces
 :sync: produces
 
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_relative_produces.py
 :emphasize-lines: 4
 ```
 
-:::
+````
 
-:::{tab-item} Decorators
+````{tab-item} Decorators
 :sync: decorators
 
 ```{warning}
@@ -241,16 +243,16 @@ You can also use absolute and relative paths as strings that obey the same rules
 If you use `depends_on` or `produces` as arguments for the task function, you will have
 access to the paths of the targets as {class}`pathlib.Path`.
 
-:::
-::::
+````
+`````
 
 ## Multiple dependencies and products
 
 Of course, tasks can have multiple dependencies and products.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_multiple1_py310.py
@@ -263,9 +265,9 @@ structures if needed.
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_multiple2_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_multiple1_py38.py
@@ -278,9 +280,9 @@ structures if needed.
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_multiple2_py38.py
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`produces`
+````{tab-item} prodouces
 :sync: produces
 
 If your task has multiple products, group them in one container like a dictionary
@@ -294,9 +296,9 @@ You can do the same with dependencies.
 ```{literalinclude} ../../../docs_src/tutorials/defining_dependencies_products_multiple2_produces.py
 ```
 
-:::
+````
 
-:::{tab-item} Decorators
+````{tab-item} Decorators
 :sync: decorators
 
 ```{warning}
@@ -405,8 +407,8 @@ def task_fit_model(depends_on, produces):
 }
 ```
 
-:::
-::::
+````
+`````
 
 (after)=
 
@@ -431,8 +433,7 @@ def task_plot_data(...):
 You can also pass a list of task functions.
 
 The second mode is to pass an expression, a substring of the name of the dependent
-tasks. Here, we can pass the function name or a significant part of the function
-name.
+tasks. Here, we can pass the function name or a significant part of the function name.
 
 ```python
 @task(after="random_data")
@@ -450,9 +451,3 @@ You will learn more about expressions in {doc}`selecting_tasks`.
 - An overview of all ways to specify dependencies and products and their strengths and
   weaknesses can be found in
   {doc}`../how_to_guides/interfaces_for_dependencies_products`.
-
-## References
-
-[^id3]: The official documentation for {mod}`pathlib`.
-
-[^id4]: A guide for pathlib by [RealPython](https://realpython.com/python-pathlib/).

docs/source/tutorials/making_tasks_persist.md

@@ -19,10 +19,10 @@ in the database such that the subsequent execution will skip the task successful
 - You want to integrate a task that you have already run elsewhere. Copy over the
   dependencies and products and the task definition and make the task persist.
 
-:::{caution}
+```{caution}
 This feature can corrupt the integrity of your project. Document why you have applied
 the decorator out of consideration for yourself and other contributors.
-:::
+```
 
 ## How to do it?
 
@@ -45,15 +45,15 @@ Running pytask will execute the task since the product is missing.
 ```
 
 After that, we accidentally changed the task's source file by formatting the file with
-Black. Without the {func}`@pytask.mark.persist <pytask.mark.persist>` decorator, the task
-would run again since the source has changed. With the decorator, a green p signals that
-the execution is skipped.
+Black. Without the {func}`@pytask.mark.persist <pytask.mark.persist>` decorator, the
+task would run again since the source has changed. With the decorator, a green p signals
+that the execution is skipped.
 
 ```{include} ../_static/md/persist-persisted.md
 ```
 
-If we rerun the task, it is skipped because nothing has changed and not because
-it is marked with {func}`@pytask.mark.persist <pytask.mark.persist>`.
+If we rerun the task, it is skipped because nothing has changed and not because it is
+marked with {func}`@pytask.mark.persist <pytask.mark.persist>`.
 
 ```{include} ../_static/md/persist-skipped.md
 ```

docs/source/tutorials/repeating_tasks_with_different_inputs.md

@@ -11,33 +11,33 @@ reproducible samples.
 Apply the {func}`@task <pytask.task>` decorator, loop over the function and supply
 different seeds and output paths as default arguments of the function.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs1_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs1_py38.py
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`produces`
+````{tab-item} produces
 :sync: produces
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs1_produces.py
 ```
 
-:::
+````
 
-:::{tab-item} Decorators
+````{tab-item} Decorators
 :sync: decorators
 
 ```{warning}
@@ -47,8 +47,8 @@ This approach is deprecated and will be removed in v0.5
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs1_decorators.py
 ```
 
-:::
-::::
+````
+`````
 
 Executing pytask gives you this:
 
@@ -59,33 +59,33 @@ Executing pytask gives you this:
 
 You can also add dependencies to repeated tasks just like with any other task.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs2_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs2_py38.py
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`produces`
+````{tab-item} produces
 :sync: produces
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs2_produces.py
 ```
 
-:::
+````
 
-:::{tab-item} Decorators
+````{tab-item} Decorators
 :sync: decorators
 
 ```{warning}
@@ -95,8 +95,8 @@ This approach is deprecated and will be removed in v0.5
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs2_decorators.py
 ```
 
-:::
-::::
+````
+`````
 
 (how-to-repeat-a-task-with-different-inputs-the-id)=
 
@@ -131,33 +131,33 @@ a combination of the argument name and the iteration counter.
 
 For example, the following function is parametrized with tuples.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs3_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs3_py38.py
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`produces`
+````{tab-item} produces
 :sync: produces
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs3_produces.py
 ```
 
-:::
+````
 
-:::{tab-item} Decorators
+````{tab-item} Decorators
 :sync: decorators
 
 ```{warning}
@@ -167,8 +167,8 @@ This approach is deprecated and will be removed in v0.5
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs3_decorators.py
 ```
 
-:::
-::::
+````
+`````
 
 Since the tuples are not converted to strings, the ids of the two tasks are
 
@@ -181,36 +181,36 @@ task_data_preparation.py::task_create_random_data[seed1]
 
 ### User-defined ids
 
-The {func}`@task <pytask.task>` decorator has an `id` keyword, allowing
-the user to set a unique name for the iteration.
+The {func}`@task <pytask.task>` decorator has an `id` keyword, allowing the user to set
+a unique name for the iteration.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs4_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs4_py38.py
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`produces`
+````{tab-item} produces
 :sync: produces
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs4_produces.py
 ```
 
-:::
+````
 
-:::{tab-item} Decorators
+````{tab-item} Decorators
 :sync: decorators
 
 ```{warning}
@@ -220,8 +220,8 @@ This approach is deprecated and will be removed in v0.5
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs4_decorators.py
 ```
 
-:::
-::::
+````
+`````
 
 produces these ids
 
@@ -237,8 +237,8 @@ and arguments. Here are three tips to organize the repetitions.
 
 1. Use suitable containers to organize your ids and the function arguments.
 
-   ::::{tab-set}
-   :::{tab-item} NamedTuple
+   `````{tab-set}
+   ````{tab-item} NamedTuple
 
    {obj}`typing.NamedTuple` or {obj}`collections.namedtuple` are useful containers to
    organize the arguments of the parametrizations. They also provide better support for
@@ -260,9 +260,9 @@ and arguments. Here are three tips to organize the repetitions.
    }
    ```
 
-   :::
+   ````
 
-   :::{tab-item} Dictionary
+   ````{tab-item} Dictionary
 
    ```python
    ID_TO_KWARGS = {
@@ -271,44 +271,44 @@ and arguments. Here are three tips to organize the repetitions.
    }
    ```
 
-   :::
-   ::::
+   ````
+   `````
 
-2. {func}`@task <pytask.task>` has a `kwargs` argument that allows you
-   inject arguments to the function instead of adding them as default arguments.
+1. {func}`@task <pytask.task>` has a `kwargs` argument that allows you inject arguments
+   to the function instead of adding them as default arguments.
 
-3. If the generation of arguments for the task function is complex, we should use a
+1. If the generation of arguments for the task function is complex, we should use a
    function.
 
 Following these three tips, the parametrization becomes
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs5_py310.py
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs5_py38.py
 ```
 
-:::
+````
 
-:::{tab-item} &#8203;`produces`
+````{tab-item} produces
 :sync: produces
 
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs5_produces.py
 ```
 
-:::
+````
 
-:::{tab-item} Decorators
+````{tab-item} Decorators
 :sync: decorators
 
 ```{warning}
@@ -318,12 +318,11 @@ This approach is deprecated and will be removed in v0.5
 ```{literalinclude} ../../../docs_src/tutorials/repeating_tasks_with_different_inputs5_decorators.py
 ```
 
-:::
-::::
+````
+`````
 
 Unpacking all the arguments can become tedious. Instead, use the `kwargs` argument of
-the {func}`@task <pytask.task>` decorator to pass keyword arguments to
-the task.
+the {func}`@task <pytask.task>` decorator to pass keyword arguments to the task.
 
 ```python
 for id_, kwargs in ID_TO_KWARGS.items():
@@ -354,8 +353,7 @@ for id_, kwargs in ID_TO_KWARGS.items():
         ...
 ```
 
-The
-{doc}`best-practices guide on parametrizations <../how_to_guides/bp_scaling_tasks>`
+The {doc}`best-practices guide on parametrizations <../how_to_guides/bp_scaling_tasks>`
 goes into even more detail on how to scale parametrizations.
 
 ## A warning on globals

docs/source/tutorials/selecting_tasks.md

@@ -105,7 +105,7 @@ pytask uses booleans, floats, integers, and strings in the task id. It replaces
 Python objects like tuples with a combination of the argument name and an iteration
 counter and separates multiple arguments via dashes.
 
-:::{seealso}
+```{seealso}
 Read this {ref}`section <how-to-repeat-a-task-with-different-inputs-the-id>` for more
 information on how ids for repeated tasks are created and can be customized.
-:::
+```

docs/source/tutorials/set_up_a_project.md

@@ -1,10 +1,10 @@
 # Set up a project
 
-Assuming you want to use pytask for a more extensive project, you want
-to organize the project as a Python package. This tutorial explains the minimal setup.
+Assuming you want to use pytask for a more extensive project, you want to organize the
+project as a Python package. This tutorial explains the minimal setup.
 
-If you want to use pytask with a collection of scripts, you can skip this lesson
-and move to the next section of the tutorials.
+If you want to use pytask with a collection of scripts, you can skip this lesson and
+move to the next section of the tutorials.
 
 The following directory tree gives an overview of the project's different parts.
 
@@ -49,11 +49,11 @@ SRC = Path(__file__).parent.resolve()
 BLD = SRC.joinpath("..", "..", "bld").resolve()
 ```
 
-:::{seealso}
+```{seealso}
 If you want to know more about the "`src` layout" and why it is NASA-approved, read
 [this article by Hynek Schlawack](https://hynek.me/articles/testing-packaging/) or this
 [setuptools article](https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#src-layout).
-:::
+```
 
 ## The `bld` directory
 
@@ -70,7 +70,7 @@ The `pyproject.toml` file is the modern configuration file for most Python packa
 apps. It contains
 
 1. the configuration for our Python package.
-2. pytask's configuration.
+1. pytask's configuration.
 
 Let us start with the configuration of the Python package, which contains general
 information about the package, like its name and version, the definition of the package
@@ -93,10 +93,10 @@ where = ["src"]
 namespaces = false
 ```
 
-:::{seealso}
+```{seealso}
 You can find more extensive information about this metadata in the documentation of
 [setuptools](https://setuptools.pypa.io/en/latest/userguide/quickstart.html).
-:::
+```
 
 Alongside the package information, we include pytask's configuration under the
 `[tool.pytask.ini_options]` section. We only tell pytask to look for tasks in
@@ -153,12 +153,12 @@ mode and it means any changes in the package's source files are immediately avai
 the installed version. Again, setuptools makes
 [a good job explaining it](https://setuptools.pypa.io/en/latest/userguide/development_mode.html).
 
-:::{important}
+```{important}
 Do not forget to rerun the editable install every time after you recreate your Python
 environment.
 
 Also, do not mix it up with the regular installation command `pip install .` because it
 will likely not work. Then, paths defined with the variables `SRC` and `BLD` in
 `config.py` will look for files relative to the location where your package is installed
 like `/home/user/miniconda3/envs/...` and not in the folder you are working in.
-:::
+```

docs/source/tutorials/using_a_data_catalog.md

@@ -56,9 +56,9 @@ create a {class}`~pytask.PickleNode` that allows you to save any Python object t
 
 The following tabs show you how to use the data catalog given the interface you prefer.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 Use `data_catalog["key"]` as an default argument to access the
@@ -69,9 +69,9 @@ Use `data_catalog["key"]` as an default argument to access the
 :emphasize-lines: 11, 22
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 Use `data_catalog["key"]` as an default argument to access the
@@ -82,9 +82,9 @@ Use `data_catalog["key"]` as an default argument to access the
 :emphasize-lines: 10, 21
 ```
 
-:::
+````
 
-:::{tab-item} ​`produces`
+````{tab-item} ​produces
 :sync: produces
 
 Use `data_catalog["key"]` as an default argument to access the
@@ -95,9 +95,9 @@ Use `data_catalog["key"]` as an default argument to access the
 :emphasize-lines: 7, 17
 ```
 
-:::
+````
 
-:::{tab-item} ​Python 3.10+ & Return
+````{tab-item} ​Python 3.10+ & Return
 :sync: return
 
 An elegant way to use the data catalog is via return type annotations. Add
@@ -111,18 +111,18 @@ You can read more about return type annotations in
 :emphasize-lines: 8, 17
 ```
 
-:::
-::::
+````
+`````
 
 ## `task_plot_data`
 
 Next, we will define the second task that consumes the data set from the previous task.
 Following one of the interfaces gives you immediate access to the
 {class}`~pandas.DataFrame` in the task without any additional line to load it.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 Use `data_catalog["key"]` as an default argument to access the
@@ -133,9 +133,9 @@ Use `data_catalog["key"]` as an default argument to access the
 :emphasize-lines: 12
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 Use `data_catalog["key"]` as an default argument to access the
@@ -146,8 +146,8 @@ Use `data_catalog["key"]` as an default argument to access the
 :emphasize-lines: 12
 ```
 
-:::
-::::
+````
+`````
 
 Finally, let's execute the two tasks.
 
@@ -192,35 +192,35 @@ The path can be absolute or relative to the module of the data catalog.
 You can now use the data catalog as in previous example and use the
 {class}`~~pathlib.Path` in the task.
 
-::::{tab-set}
+`````{tab-set}
 
-:::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 :sync: python310plus
 
 ```{literalinclude} ../../../docs_src/tutorials/using_a_data_catalog_5_py310.py
 :emphasize-lines: 11, 12
 ```
 
-:::
+````
 
-:::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 :sync: python38plus
 
 ```{literalinclude} ../../../docs_src/tutorials/using_a_data_catalog_5_py38.py
 :emphasize-lines: 11, 12
 ```
 
-:::
+````
 
-:::{tab-item} ​Python 3.10+ & Return
+````{tab-item} ​Python 3.10+ & Return
 :sync: return
 
 ```{literalinclude} ../../../docs_src/tutorials/using_a_data_catalog_5_py310_return.py
 :emphasize-lines: 9, 10
 ```
 
-:::
-::::
+````
+`````
 
 ## Developing with the `DataCatalog`
 

docs/source/tutorials/write_a_task.md

@@ -4,8 +4,8 @@ Starting from the project structure in the {doc}`previous tutorial <set_up_a_pro
 you will learn how to write your first task.
 
 The task, `task_create_random_data`, will be defined in
-`src/my_project/task_data_preparation.py`, and it will generate a data set stored
-in `bld/data.pkl`.
+`src/my_project/task_data_preparation.py`, and it will generate a data set stored in
+`bld/data.pkl`.
 
 The `task_` prefix for modules and task functions is important so that pytask
 automatically discovers them.
@@ -34,57 +34,57 @@ The following interfaces are different ways to specify the products of a task wh
 necessary for pytask to correctly run a workflow. The interfaces are ordered from most
 (left) to least recommended (right).
 
-:::{important}
+```{important}
 You cannot mix different interfaces for the same task. Choose only one.
-:::
+```
 
-:::::{tab-set}
+`````{tab-set}
 
-::::{tab-item} Python 3.10+
+````{tab-item} Python 3.10+
 
 The task accepts the argument `path` that points to the file where the data set will be
 stored. The path is passed to the task via the default value, `BLD / "data.pkl"`. To
 indicate that this file is a product we add some metadata to the argument.
 
 Look at the type hint `Annotated[Path, Product]`. It uses the
 {obj}`~typing.Annotated` syntax. The first entry is the type of the argument,
-{class}`~pathlib.Path`. The second entry is {class}`pytask.Product` that marks this
+{class}`~pathlib.Path`. The second entry is {class}`~pytask.Product` that marks this
 argument as a product.
 
 ```{literalinclude} ../../../docs_src/tutorials/write_a_task_py310.py
 :emphasize-lines: 3, 11
 ```
 
-:::{tip}
+```{tip}
 If you want to refresh your knowledge about type hints, read
 [this guide](../type_hints.md).
-:::
+```
 
-::::
+````
 
-::::{tab-item} Python 3.8+
+````{tab-item} Python 3.8+
 
 The task accepts the argument `path` that points to the file where the data set will be
 stored. The path is passed to the task via the default value, `BLD / "data.pkl"`. To
 indicate that this file is a product we add some metadata to the argument.
 
 Look at the type hint `Annotated[Path, Product]`. It uses the
 {obj}`~typing.Annotated` syntax. The first entry is the type of the argument,
-{class}`~pathlib.Path`. The second entry is {class}`pytask.Product` that marks this
+{class}`~pathlib.Path`. The second entry is {class}`~pytask.Product` that marks this
 argument as a product.
 
 ```{literalinclude} ../../../docs_src/tutorials/write_a_task_py38.py
 :emphasize-lines: 8, 11
 ```
 
-:::{tip}
+```{tip}
 If you want to refresh your knowledge about type hints, read
 [this guide](../type_hints.md).
-:::
+```
 
-::::
+````
 
-::::{tab-item} &#8203;`produces`
+````{tab-item} produces
 
 Tasks can use `produces` as an argument name. Every value, or in this case path, passed
 to this argument is automatically treated as a task product. Here, the path is given by
@@ -94,9 +94,9 @@ the default value of the argument.
 :emphasize-lines: 9
 ```
 
-::::
+````
 
-::::{tab-item} Decorators
+````{tab-item} Decorators
 
 ```{warning}
 This approach is deprecated and will be removed in v0.5
@@ -113,8 +113,8 @@ an argument name to use the path inside the task function.
 To let pytask track the product of the task, you need to use the
 {func}`@pytask.mark.produces <pytask.mark.produces>` decorator.
 
-::::
-:::::
+````
+`````
 
 Now, execute pytask to collect tasks in the current and subsequent directories.
 
@@ -125,9 +125,9 @@ Now, execute pytask to collect tasks in the current and subsequent directories.
 
 ## Customize task names
 
-Use the {func}`@task <pytask.task>` decorator to mark a function as a
-task regardless of its function name. You can optionally pass a new name for the task.
-Otherwise, pytask uses the function name.
+Use the {func}`@task <pytask.task>` decorator to mark a function as a task regardless of
+its function name. You can optionally pass a new name for the task. Otherwise, pytask
+uses the function name.
 
 ```python
 from pytask import task
@@ -148,10 +148,10 @@ def create_random_data():
     ...
 ```
 
-:::{warning}
+```{warning}
 Since v0.4 users should use {func}`@task <pytask.task>` over
 {func}`@pytask.mark.task <pytask.mark.task>` which will be removed in v0.5.
-:::
+```
 
 ## Customize task module names
 

pyproject.toml

@@ -198,3 +198,7 @@ exclude_also = [
     "\\.\\.\\.",
     "def __repr__",
 ]
+
+[tool.mdformat]
+wrap = 88
+end_of_line = "keep"

src/_pytask/nodes.py

@@ -221,12 +221,10 @@ class PythonNode(PNode):
         objects.
     node_info
         The infos acquired while collecting the node.
-    signature
-        The signature of the node.
 
     Examples
     --------
-    To allow a :class:`~pytask.PythonNode` to hash a dictionary, you need to pass your
+    To allow a :class:`PythonNode` to hash a dictionary, you need to pass your
     own hashing function. For example, from the :mod:`deepdiff` library.
 
     >>> from deepdiff import DeepHash
@@ -293,7 +291,7 @@ def state(self) -> str | None:
 
 
 @define
-class PickleNode:
+class PickleNode(PPathNode):
     """A node for pickle files.
 
     Attributes