pytask-dev · tobiasraabe · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026
diff --git a/.gitignore b/.gitignore
@@ -30,3 +30,4 @@ tests/test_jupyter/*.txt
 .venv
 docs/jupyter_execute
 .DS_Store
+docs/source/reference_guides/commands.md
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -53,7 +53,7 @@ repos:
             mdformat-pyproject>=0.0.2,
         ]
         files: (docs/.)
-        exclude: (docs/source/reference_guides/hookspecs\.md|docs/source/api/.*\.md|docs/source/how_to_guides/capture_warnings\.md|docs/source/how_to_guides/hashing_inputs_of_tasks\.md|docs/source/how_to_guides/provisional_nodes_and_task_generators\.md|docs/source/how_to_guides/remote_files\.md|docs/source/how_to_guides/writing_custom_nodes\.md|docs/source/tutorials/defining_dependencies_products\.md|docs/source/tutorials/using_a_data_catalog\.md)
+        exclude: (docs/source/reference_guides/hookspecs\.md|docs/source/reference_guides/api/.*\.md|docs/source/how_to_guides/capture_warnings\.md|docs/source/how_to_guides/hashing_inputs_of_tasks\.md|docs/source/how_to_guides/provisional_nodes_and_task_generators\.md|docs/source/how_to_guides/remote_files\.md|docs/source/how_to_guides/writing_custom_nodes\.md|docs/source/tutorials/defining_dependencies_products\.md|docs/source/tutorials/using_a_data_catalog\.md)
 -   repo: https://github.com/kynan/nbstripout
     rev: 0.9.1
     hooks:

diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -127,3 +127,34 @@ body[data-md-color-scheme="slate"] .home-tile p {
         box-shadow: 0 12px 26px rgba(2, 6, 23, 0.46);
     }
 }
+
+.md-typeset dl.cli-reference {
+    margin: 0.75rem 0 1.25rem;
+}
+
+.md-typeset dl.cli-reference dt {
+    margin: 0.85rem 0 0;
+    font-weight: 500;
+}
+
+.md-typeset dl.cli-reference dd {
+    margin: 0.2rem 0 0.75rem 1.5rem;
+}
+
+.md-typeset dl.cli-reference dd p {
+    margin: 0;
+}
+
+.md-typeset dl.cli-reference dd p + p {
+    margin-top: 0.25rem;
+    color: var(--md-default-fg-color--light);
+}
+
+.md-typeset dl.cli-reference dt a,
+.md-typeset dl.cli-reference dt a:hover,
+.md-typeset dl.cli-reference dt a:focus,
+.md-typeset dl.cli-reference dt a:visited {
+    color: inherit;
+    text-decoration: none;
+    border-bottom: 0;
+}
diff --git a/docs/source/commands/build.md b/docs/source/commands/build.md
diff --git a/docs/source/commands/clean.md b/docs/source/commands/clean.md
diff --git a/docs/source/commands/collect.md b/docs/source/commands/collect.md
diff --git a/docs/source/commands/dag.md b/docs/source/commands/dag.md
diff --git a/docs/source/commands/index.md b/docs/source/commands/index.md
diff --git a/docs/source/commands/markers.md b/docs/source/commands/markers.md
diff --git a/docs/source/commands/profile.md b/docs/source/commands/profile.md
diff --git a/docs/source/how_to_guides/bp_complex_task_repetitions.md b/docs/source/how_to_guides/bp_complex_task_repetitions.md
@@ -99,8 +99,8 @@ When you are using the `.name` attributes of the dimensions and multi-dimensiona
 objects like in the example above, you ensure that the names of dimensions are included
 in all downstream tasks.
 
-Thus, you can simply call [`pytask -k`](../commands/build.md#options) with the following
-expression to execute all tasks related to the logit model.
+Thus, you can simply call [`pytask -k`](../reference_guides/commands.md#pytask-build--k)
+with the following expression to execute all tasks related to the logit model.
 
 ```console
 pytask -k logit

diff --git a/docs/source/how_to_guides/capture_warnings.md b/docs/source/how_to_guides/capture_warnings.md
@@ -71,14 +71,14 @@ configured by the `filterwarnings` configuration option.
 ## Disabling warnings summary
 
 Although not recommended, you can use the
-[`--disable-warnings`](../commands/build.md#options) command-line option to suppress the
+[`--disable-warnings`](../reference_guides/commands.md#pytask-build--disable-warnings) command-line option to suppress the
 warning summary entirely from the test run output.
 
 ## Debugging warnings
 
 Sometimes it is not clear which line of code triggered a warning. To find the location,
 you can turn warnings into exceptions and then use the
-[`pytask build --pdb`](../commands/build.md#options) flag to enter the debugger.
+[`pytask build --pdb`](../reference_guides/commands.md#pytask-build--pdb) flag to enter the debugger.
 
 You can use the configuration to convert warnings to errors by setting
 

diff --git a/docs/source/how_to_guides/extending_pytask.md b/docs/source/how_to_guides/extending_pytask.md
@@ -19,8 +19,9 @@ More general information about pluggy can be found in its
 There are two ways to add new
 [hook implementations](../glossary.md#hook-implementation).
 
-1. Using the [`pytask build --hook-module`](../commands/build.md#options) commandline
-    option or the `hook_module` configuration value.
+1. Using the
+    [`pytask build --hook-module`](../reference_guides/commands.md#pytask-build--hook-module)
+    commandline option or the `hook_module` configuration value.
 1. Packaging your [plugin](../glossary.md#plugin) as a Python package to publish and
     share it.
 
@@ -55,8 +56,8 @@ hook_module = ["myproject.hooks"]
 ```
 
 In `hooks.py` we can add another commandline option to
-[`pytask build`](../commands/build.md) by providing an additional
-[hook implementation](../glossary.md#hook-implementation) for the
+[`pytask build`](../reference_guides/commands.md#pytask-build) by providing an
+additional [hook implementation](../glossary.md#hook-implementation) for the
 [hook specification](../glossary.md#hook-specification)
 `_pytask.hookspecs.pytask_extend_command_line_interface`.
 

diff --git a/docs/source/how_to_guides/how_to_influence_build_order.md b/docs/source/how_to_guides/how_to_influence_build_order.md
@@ -35,8 +35,8 @@ def task_second():
     print("I'm first.")
 ```
 
-The execution yields (use [`-s`](../commands/build.md#options) to make the output
-visible in the terminal)
+The execution yields (use [`-s`](../reference_guides/commands.md#pytask-build--s) to
+make the output visible in the terminal)
 
 --8<-- "docs/source/_static/md/try-first.md"
 

diff --git a/docs/source/how_to_guides/portability.md b/docs/source/how_to_guides/portability.md
@@ -14,8 +14,8 @@ Use this checklist when you move a project to another machine or environment.
 
 1. **Update state once on the source machine.**
 
-Run a normal build with [`pytask build`](../commands/build.md) so `pytask.lock` is up to
-date:
+Run a normal build with [`pytask build`](../reference_guides/commands.md#pytask-build)
+so `pytask.lock` is up to date:
 
 ````
 ```console
@@ -85,7 +85,7 @@ tasks run. If tasks are removed or renamed, their old entries remain as stale da
 are ignored.
 
 To clean up stale entries without deleting the file, run
-[`pytask build --clean-lockfile`](../commands/build.md#options):
+[`pytask build --clean-lockfile`](../reference_guides/commands.md#pytask-build--clean-lockfile):
 
 ```console
 $ pytask build --clean-lockfile

diff --git a/docs/source/index.md b/docs/source/index.md
@@ -70,5 +70,3 @@ If you want to know more about pytask, dive into one of the following topics.
     <p>API and implementation details for developers and plugin authors.</p>
   </a>
 </div>
-
-For command-line usage, see the [CLI reference](commands/index.md).
diff --git a/docs/source/reference_guides/api.md b/docs/source/reference_guides/api.md
diff --git a/docs/source/api/cli_and_programmatic.md → ...erence_guides/api/cli_and_programmatic.md b/docs/source/api/cli_and_programmatic.md → ...erence_guides/api/cli_and_programmatic.md
@@ -2,7 +2,8 @@
 
 This page documents the public CLI-related imports from `pytask`.
 
-For command usage and options, see the [CLI reference](../commands/index.md).
+For command usage and options, see the
+[command reference](../commands.md).
 
 ## Command Line Entry Point
 

diff --git a/...source/api/core_classes_and_exceptions.md → ...guides/api/core_classes_and_exceptions.md b/...source/api/core_classes_and_exceptions.md → ...guides/api/core_classes_and_exceptions.md
diff --git a/docs/source/api/functional_interfaces.md → ...rence_guides/api/functional_interfaces.md b/docs/source/api/functional_interfaces.md → ...rence_guides/api/functional_interfaces.md
diff --git a/docs/source/api/index.md → docs/source/reference_guides/api/index.md b/docs/source/api/index.md → docs/source/reference_guides/api/index.md
diff --git a/docs/source/api/marks.md → docs/source/reference_guides/api/marks.md b/docs/source/api/marks.md → docs/source/reference_guides/api/marks.md
diff --git a/docs/source/api/nodes_and_tasks.md → ...e/reference_guides/api/nodes_and_tasks.md b/docs/source/api/nodes_and_tasks.md → ...e/reference_guides/api/nodes_and_tasks.md
diff --git a/...urce/api/outcomes_reports_and_warnings.md → ...ides/api/outcomes_reports_and_warnings.md b/...urce/api/outcomes_reports_and_warnings.md → ...ides/api/outcomes_reports_and_warnings.md
diff --git a/docs/source/api/utilities_and_typing.md → ...erence_guides/api/utilities_and_typing.md b/docs/source/api/utilities_and_typing.md → ...erence_guides/api/utilities_and_typing.md
-Original file line number
+Diff line change
@@ Expand Up @@
         <p>API and implementation details for developers and plugin authors.</p>
       </a>
     </div>
-    For command-line usage, see the [CLI reference](commands/index.md).