Document new interface.

.pre-commit-config.yaml

@@ -28,6 +28,13 @@ repos:
     hooks:
     -   id: reorder-python-imports
         args: [--py38-plus, --add-import, 'from __future__ import annotations']
+        exclude: ^(docs_src/)
+-   repo: https://github.com/asottile/reorder-python-imports
+    rev: v3.9.0
+    hooks:
+    -   id: reorder-python-imports
+        args: [--py38-plus]
+        files: ^(docs_src/)
 -   repo: https://github.com/asottile/setup-cfg-fmt
     rev: v2.4.0
     hooks:
@@ -49,8 +56,8 @@ repos:
     rev: 1.5.0
     hooks:
     -   id: interrogate
-        args: [-vv, --fail-under=75]
-        exclude: ^(tests/|docs/|scripts/)
+        args: [-v, --fail-under=75]
+        exclude: ^(tests/|docs/|scripts/|docs_src/)
 -   repo: https://github.com/pre-commit/mirrors-mypy
     rev: 'v1.5.1'
     hooks:
@@ -93,13 +100,18 @@ repos:
                 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/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/set_up_a_project.md|
+                docs/source/tutorials/write_a_task.md
             )$
 - repo: https://github.com/kynan/nbstripout
   rev: 0.6.1

MANIFEST.in

@@ -10,5 +10,6 @@ exclude *.yml
 exclude tox.ini
 
 prune docs
+prune docs_src
 prune scripts
 prune tests

docs/source/_static/css/custom.css

@@ -18,94 +18,14 @@ li pre {
   padding-left: 20px
 }
 
-.termynal-comment {
-    color: #4a968f;
-    font-style: italic;
-    display: block;
+.highlight {
+    background: #f5f5f5
 }
 
-.termy [data-termynal] {
-    white-space: pre-wrap;
+.highlight button.copybtn{
+    background-color: #f5f5f5;
 }
 
-a.external-link::after {
-    /* \00A0 is a non-breaking space
-        to make the mark be on the same line as the link
-    */
-    content: "\00A0[↪]";
-}
-
-a.internal-link::after {
-    /* \00A0 is a non-breaking space
-        to make the mark be on the same line as the link
-    */
-    content: "\00A0↪";
-}
-
-
-:root {
-    --termynal-green: #137C39;
-    --termynal-red: #BF2D2D;
-    --termynal-yellow: #F4C041;
-    --termynal-white: #f2f2f2;
-    --termynal-black: #0c0c0c;
-    --termynal-blue: #11a8cd;
-    --termynal-grey: #7f7f7f;
-}
-
-
-.termynal-failed {
-    color: var(--termynal-red);
-}
-
-.termynal-failed-textonly {
-    color: var(--termynal-white);
-    background: var(--termynal-red);
-    font-weight: bold;
-}
-
-.termynal-success {
-    color: var(--termynal-green);
-}
-
-.termynal-success-textonly {
-    color: var(--termynal-white);
-    background: var(--termynal-green);
-    font-weight: bold;
-}
-
-.termynal-skipped {
-    color: var(--termynal-yellow);
-}
-
-.termynal-skipped-textonly {
-    color: var(--termynal-black);
-    background: var(--termynal-yellow);
-    font-weight: bold;
-}
-
-.termynal-warning {
-    color: var(--termynal-yellow);
-}
-.termynal-command {
-    color: var(--termynal-green);
-    font-weight: bold;
-}
-.termynal-option {
-    color: var(--termynal-yellow);
-    font-weight: bold;
-}
-.termynal-switch {
-    color: var(--termynal-red);
-    font-weight: bold;
-}
-.termynal-metavar {
-    color: yellow;
-    font-weight: bold;
-}
-.termynal-dim {
-    color: var(--termynal-grey);
-}
-.termynal-number {
-    color: var(--termynal-blue);
+.highlight button.copybtn:hover {
+    background-color: #f5f5f5;
 }

docs/source/_static/css/termynal_custom.css

@@ -0,0 +1,95 @@
+.termynal-comment {
+    color: #4a968f;
+    font-style: italic;
+    display: block;
+}
+
+.termy [data-termynal] {
+    white-space: pre-wrap;
+}
+
+a.external-link::after {
+    /* \00A0 is a non-breaking space
+        to make the mark be on the same line as the link
+    */
+    content: "\00A0[↪]";
+}
+
+a.internal-link::after {
+    /* \00A0 is a non-breaking space
+        to make the mark be on the same line as the link
+    */
+    content: "\00A0↪";
+}
+
+:root {
+    --termynal-green: #137C39;
+    --termynal-red: #BF2D2D;
+    --termynal-yellow: #F4C041;
+    --termynal-white: #f2f2f2;
+    --termynal-black: #0c0c0c;
+    --termynal-blue: #11a8cd;
+    --termynal-grey: #7f7f7f;
+}
+
+.termynal-failed {
+    color: var(--termynal-red);
+}
+
+.termynal-failed-textonly {
+    color: var(--termynal-white);
+    background: var(--termynal-red);
+    font-weight: bold;
+}
+
+.termynal-success {
+    color: var(--termynal-green);
+}
+
+.termynal-success-textonly {
+    color: var(--termynal-white);
+    background: var(--termynal-green);
+    font-weight: bold;
+}
+
+.termynal-skipped {
+    color: var(--termynal-yellow);
+}
+
+.termynal-skipped-textonly {
+    color: var(--termynal-black);
+    background: var(--termynal-yellow);
+    font-weight: bold;
+}
+
+.termynal-warning {
+    color: var(--termynal-yellow);
+}
+
+.termynal-command {
+    color: var(--termynal-green);
+    font-weight: bold;
+}
+
+.termynal-option {
+    color: var(--termynal-yellow);
+    font-weight: bold;
+}
+
+.termynal-switch {
+    color: var(--termynal-red);
+    font-weight: bold;
+}
+
+.termynal-metavar {
+    color: yellow;
+    font-weight: bold;
+}
+
+.termynal-dim {
+    color: var(--termynal-grey);
+}
+
+.termynal-number {
+    color: var(--termynal-blue);
+}

docs/source/conf.py

@@ -72,11 +72,12 @@
 }
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3.9", None),
     "click": ("https://click.palletsprojects.com/en/8.0.x/", None),
-    "pluggy": ("https://pluggy.readthedocs.io/en/latest", None),
     "networkx": ("https://networkx.org/documentation/stable", None),
+    "pandas": ("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
@@ -96,7 +97,7 @@
 # Add any paths that contain custom static files (such as style sheets) here, relative
 # to this directory. They are copied after the built-in static files, so a file named
 # "default.css" will overwrite the built-in "default.css".
-html_css_files = ["css/termynal.css", "css/custom.css"]
+html_css_files = ["css/termynal.css", "css/termynal_custom.css", "css/custom.css"]
 
 html_js_files = ["js/termynal.js", "js/custom.js"]
 

docs/source/glossary.md

@@ -38,4 +38,9 @@ private function
 public function
     A function whose does not start with an underscore. The function can be imported
     in other modules.
+
+PyTree
+    A PyTree is a tree-like structure built out of tuples, lists, and dictionaries and
+    other container types if registered. Any other object that is not a registered
+    container is treated as a node in the tree.
 ```

docs/source/how_to_guides/bp_scalable_repetitions_of_tasks.md

@@ -85,7 +85,7 @@ The task file `task_prepare_data.py` uses these objects to build the parametriza
 ```python
 # Content of task_prepare_data.py
 
-import pytask
+from pytask import task
 
 from my_project.data_preparation.config import DATA
 from my_project.data_preparation.config import path_to_input_data
@@ -107,14 +107,13 @@ _ID_TO_KWARGS = _create_parametrization(DATA)
 
 for id_, kwargs in _ID_TO_KWARGS.items():
 
-    @pytask.mark.task(id=id_, kwargs=kwargs)
+    @task(id=id_, kwargs=kwargs)
     def task_prepare_data(depends_on, produces):
         ...
 ```
 
-All arguments for the loop and the {func}`@pytask.mark.task <pytask.mark.task>`
-decorator is built within a function to keep the logic in one place and the module's
-namespace clean.
+All arguments for the loop and the {func}`@task <pytask.task>` decorator is built within
+a function to keep the logic in one place and the module's namespace clean.
 
 Ids are used to make the task {ref}`ids <ids>` more descriptive and to simplify their
 selection with {ref}`expressions <expressions>`. Here is an example of the task ids with
@@ -163,7 +162,7 @@ And here is the task file.
 ```python
 # Content of task_estimate_models.py
 
-import pytask
+from pytask import task
 
 from my_project.data_preparation.config import path_to_processed_data
 from my_project.estimations.config import ESTIMATIONS
@@ -190,7 +189,7 @@ _ID_TO_KWARGS = _create_parametrization(ESTIMATIONS)
 
 for id_, kwargs in _ID_TO_KWARGS.items():
 
-    @pytask.mark.task(id=id_, kwargs=kwars)
+    @task(id=id_, kwargs=kwars)
     def task_estmate_models(depends_on, model, produces):
         if model == "linear_probability":
             ...