Refine docs cross references

Author: tobiasraabe

CHANGELOG.md

@@ -7,17 +7,17 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
 
 ## Unreleased
 
-- {pull}`787` makes the `attributes` field mandatory on `PNode` and
+- [#787](https://github.com/pytask-dev/pytask/pull/787) makes the `attributes` field mandatory on `PNode` and
   `PProvisionalNode`, and preserves existing node attributes when loading entries from
   the data catalog.
-- {pull}`744` Removed the direct dependency on attrs and migrated internal models to
+- [#744](https://github.com/pytask-dev/pytask/pull/744) removes the direct dependency on attrs and migrates internal models to
   dataclasses.
 - [#766](https://github.com/pytask-dev/pytask/pull/766) moves runtime profiling persistence from SQLite to a JSON snapshot plus
   append-only journal in `.pytask/`, keeping runtime data resilient to crashes and
   compacted on normal build exits.
 - [#776](https://github.com/pytask-dev/pytask/pull/776) clears decoration-time `annotation_locals` snapshots after collection so
   task functions remain picklable in process-based parallel backends.
-- {pull}`788` updates debugger interaction tests to support Python-version-specific
+- [#788](https://github.com/pytask-dev/pytask/pull/788) updates debugger interaction tests to support Python-version-specific
   `pdb` stepping behavior and avoid frame-specific assumptions on repeated breakpoints.
 
 ## 0.5.8 - 2025-12-30

docs/source/api/utilities_and_typing.md

@@ -6,6 +6,7 @@
     options:
       show_root_heading: true
       show_signature: true
+::: pytask.get_state_of_path
 ::: pytask.path.hash_path
 
 ## Tree Utilities

docs/source/how_to_guides/capture_warnings.md

@@ -62,8 +62,8 @@ configured by the `filterwarnings` configuration option.
 !!! important
 
     Note that the type of warning needs to be importable. For example, `UserWarning` is a
-    built-in warning with no module specified. `SettingWithCopyWarning` though needs to be
-    imported from `pandas.errors`.
+    built-in warning with no module specified. \[`pandas.errors.SettingWithCopyWarning`\][]
+    though needs to be imported from \[`pandas.errors`\][].
 
 ## Disabling warnings summary
 

docs/source/how_to_guides/hashing_inputs_of_tasks.md

@@ -1,7 +1,8 @@
 # Hashing inputs of tasks
 
-Any input to a task function is parsed by pytask's nodes. For example, `pathlib.Path`s
-are parsed by [pytask.PathNode](../api/nodes_and_tasks.md#pytask.PathNode)s. The
+Any input to a task function is parsed by pytask's nodes. For example,
+\[`pathlib.Path`\][]s are parsed by
+[pytask.PathNode](../api/nodes_and_tasks.md#pytask.PathNode)s. The
 [pytask.PathNode](../api/nodes_and_tasks.md#pytask.PathNode) handles among other things
 how changes in the underlying file are detected.
 

docs/source/how_to_guides/provisional_nodes_and_task_generators.md

@@ -35,15 +35,20 @@ where pytask can find the files. The files are described with a root path (defau
 the directory of the task module) and a glob pattern (default is `*`).
 
 When we use the [pytask.DirectoryNode](../api/nodes_and_tasks.md#pytask.DirectoryNode)
-as a product annotation, we get access to the `root_dir` as a `pathlib.Path` object
-inside the function, which allows us to store the files.
+as a product annotation, we get access to the `root_dir` as a \[`pathlib.Path`\][]
+object inside the function, which allows us to store the files.
 
 !!! note
 
-    The `pytask.DirectoryNode` is a provisional node that implements
-    `pytask.PProvisionalNode`. A provisional node is not a `pytask.PNode`, but when its
-    `pytask.PProvisionalNode.collect` method is called, it returns actual nodes. A
-    `pytask.DirectoryNode`, for example, returns `pytask.PathNode`.
+    The [`pytask.DirectoryNode`](../api/nodes_and_tasks.md#pytask.DirectoryNode) is a
+    provisional node that implements
+    [`pytask.PProvisionalNode`](../api/nodes_and_tasks.md#pytask.PProvisionalNode). A
+    provisional node is not a [`pytask.PNode`](../api/nodes_and_tasks.md#pytask.PNode), but
+    when its
+    [`pytask.PProvisionalNode.collect`](../api/nodes_and_tasks.md#pytask.PProvisionalNode.collect)
+    method is called, it returns actual nodes. A
+    [`pytask.DirectoryNode`](../api/nodes_and_tasks.md#pytask.DirectoryNode), for example,
+    returns a [`pytask.PathNode`](../api/nodes_and_tasks.md#pytask.PathNode).
 
 ## Depending on provisional nodes
 
@@ -57,8 +62,8 @@ downloaded.
 --8<-- "docs_src/how_to_guides/provisional_task.py"
 ```
 
-To reference the files that will be downloaded, we use the
-[pytask.DirectoryNode](../api/nodes_and_tasks.md#pytask.DirectoryNode) is a dependency.
+To reference the files that will be downloaded, we use
+[pytask.DirectoryNode](../api/nodes_and_tasks.md#pytask.DirectoryNode) as a dependency.
 Before the task is executed, the list of files in the folder defined by the root path
 and the pattern are automatically collected and passed to the task.
 

docs/source/how_to_guides/remote_files.md

@@ -8,9 +8,9 @@ lots of use cases to deal with remote files.
 - You store the workflow results in remote storage to save and distribute them.
 
 pytask uses [universal-pathlib](https://github.com/fsspec/universal_pathlib) to work
-with remote files. The package provides a `pathlib`-like interface, making it very easy
-to interact with files from an HTTP(S)-, Dropbox-, S3-, GCP-, Azure-based filesystem,
-and many more.
+with remote files. The package provides a \[`pathlib`\][]-like interface, making it very
+easy to interact with files from an HTTP(S)-, Dropbox-, S3-, GCP-, Azure-based
+filesystem, and many more.
 
 ## HTTP(S)-based filesystem
 

docs/source/how_to_guides/writing_custom_nodes.md

@@ -3,17 +3,18 @@
 In the previous tutorials and how-to guides, you learned that dependencies and products
 can be represented as plain Python objects with
 [pytask.PythonNode](../api/nodes_and_tasks.md#pytask.PythonNode) or as paths where every
-`pathlib.Path` is converted to a
+\[`pathlib.Path`\][] is converted to a
 [pytask.PathNode](../api/nodes_and_tasks.md#pytask.PathNode).
 
 In this how-to guide, you will learn about the general concept of nodes and how to write
 your own to improve your workflows.
 
 ## Use-case
 
-A typical task operation is to load data like a `pandas.DataFrame` from a pickle file,
-transform it, and store it on disk. The usual way would be to use paths to point to
-inputs and outputs and call `pandas.read_pickle` and `pandas.DataFrame.to_pickle`.
+A typical task operation is to load data like a \[`pandas.DataFrame`\][] from a pickle
+file, transform it, and store it on disk. The usual way would be to use paths to point
+to inputs and outputs and call \[`pandas.read_pickle`\][] and
+\[`pandas.DataFrame.to_pickle`\][].
 
 ```py
 --8<-- "docs_src/how_to_guides/writing_custom_nodes_example_1.py"
@@ -23,7 +24,7 @@ To remove IO operations from the task and delegate them to pytask, we will repli
 [pytask.PickleNode](../api/nodes_and_tasks.md#pytask.PickleNode) that automatically
 loads and stores Python objects.
 
-And we pass the value to `df` via `typing.Annotated` to preserve the type hint.
+And we pass the value to `df` via \[`typing.Annotated`\][] to preserve the type hint.
 
 The result will be the following task.
 
@@ -82,28 +83,34 @@ Here are some explanations.
     [pytask.PickleNode.from_path](../api/nodes_and_tasks.md#pytask.PickleNode.from_path)
     is a convenient method to instantiate the class.
 
-- The method `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.
+- The method
+    [`pytask.PickleNode.state`](../api/nodes_and_tasks.md#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 `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
+- pytask calls
+    [`pytask.PickleNode.load`](../api/nodes_and_tasks.md#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
     [pytask.Product](../api/utilities_and_typing.md#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
-    `pytask.PickleNode.save` themselves.
+    [`pytask.PickleNode.save`](../api/nodes_and_tasks.md#pytask.PickleNode.save)
+    themselves.
 
-- `pytask.PickleNode.save` is called when a task function returns and allows to save the
-    return values.
+- [`pytask.PickleNode.save`](../api/nodes_and_tasks.md#pytask.PickleNode.save) is called
+    when a task function returns and allows to save the return values.
 
 ## Improvements
 
-Usually, you would like your custom node to work with `pathlib.Path` objects and
-`upath.UPath` objects allowing to work with remote filesystems. To simplify getting the
-state of the node, you can use the `pytask.get_state_of_path` function.
+Usually, you would like your custom node to work with \[`pathlib.Path`\][] objects and
+\[`upath.UPath`\][] objects allowing to work with remote filesystems. To simplify
+getting the state of the node, you can use the
+[`pytask.get_state_of_path`](../api/utilities_and_typing.md#pytask.get_state_of_path)
+function.
 
 ## Conclusion
 

docs/source/plugin_list.md

@@ -1,7 +1,7 @@
 # Plugin List
 
-PyPI projects that match `pytask-*` are considered [plugins](glossary.md#plugin) and are
-listed automatically. Packages classified as inactive are excluded.
+PyPI projects that match `pytask-*` are considered plugins and are listed automatically.
+Packages classified as inactive are excluded.
 
 !!! warning
 

docs/source/tutorials/defining_dependencies_products.md

@@ -66,7 +66,7 @@ Let's revisit the task from the [previous tutorial](write_a_task.md) that we def
 
 !!! tip
 
-    If you do not know about `pathlib` check out this guide by
+    If you do not know about \[`pathlib`\][] check out this guide by
     [RealPython](https://realpython.com/python-pathlib/). The module is beneficial for
     handling paths conveniently and across platforms.
 
@@ -83,8 +83,9 @@ we will define it in `task_plot_data.py`.
     To specify the task relies on `data.pkl`, add the path to the function signature with
     any argument name (here `path_to_data`).
 
-    pytask assumes that all function arguments that do not have a `pytask.Product`
-    annotation are dependencies of the task.
+    pytask assumes that all function arguments that do not have a
+    [`pytask.Product`](../api/utilities_and_typing.md#pytask.Product) annotation are
+    dependencies of the task.
 
     ```py hl_lines="12"
     --8<-- "docs_src/tutorials/defining_dependencies_products_dependencies_py310.py"

docs/source/tutorials/using_a_data_catalog.md

@@ -86,7 +86,7 @@ The following tabs show you how to use the data catalog given the interface you
 
     Use `data_catalog["data"]` as an default argument to access the
     [`pytask.PickleNode`](../api/nodes_and_tasks.md#pytask.PickleNode) within the task. When
-    you are done transforming your `pandas.DataFrame`, save it with
+    you are done transforming your \[`pandas.DataFrame`\][], save it with
     [`pytask.PNode.save`](../api/nodes_and_tasks.md#pytask.PNode.save).
 
     ```py hl_lines="11 22" title="task_data_preparation.py"
@@ -97,7 +97,7 @@ The following tabs show you how to use the data catalog given the interface you
 
     Use `data_catalog["data"]` as an default argument to access the
     [`pytask.PickleNode`](../api/nodes_and_tasks.md#pytask.PickleNode) within the task. When
-    you are done transforming your `pandas.DataFrame`, save it with
+    you are done transforming your \[`pandas.DataFrame`\][], save it with
     [`pytask.PNode.save`](../api/nodes_and_tasks.md#pytask.PNode.save).
 
     ```py hl_lines="7 17" title="task_data_preparation.py"
@@ -122,8 +122,7 @@ The following tabs show you how to use the data catalog given the interface you
 
 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
-[`pandas.DataFrame`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html)
-in the task without any additional line to load it.
+\[`pandas.DataFrame`\][] in the task without any additional line to load it.
 
 ```py hl_lines="13" title="task_plot_data.py"
 --8<-- "docs_src/tutorials/using_a_data_catalog_3_py310.py"
@@ -170,13 +169,13 @@ path means the location is relative to the module of the data catalog.
 --8<-- "docs_src/tutorials/using_a_data_catalog_4.py"
 ```
 
-You can now use the data catalog as in the previous example and use the `pathlib.Path`
-in the task.
+You can now use the data catalog as in the previous example and use the
+\[`pathlib.Path`\][] in the task.
 
 !!! note
 
-    Note that the value of `data_catalog["csv"]` inside the task becomes a `pathlib.Path`.
-    It is because a `pathlib.Path` in
+    Note that the value of `data_catalog["csv"]` inside the task becomes a
+    \[`pathlib.Path`\][]. It is because a \[`pathlib.Path`\][] in
     [`pytask.DataCatalog.add`](../api/core_classes_and_exceptions.md#pytask.DataCatalog.add)
     is not parsed to a [`pytask.PickleNode`](../api/nodes_and_tasks.md#pytask.PickleNode)
     but a [`pytask.PathNode`](../api/nodes_and_tasks.md#pytask.PathNode).
@@ -219,6 +218,6 @@ WindowsPath('C:\Users\pytask-dev\git\my_project\file.csv')
 
 `data_catalog["data"]` was stored with a
 [`pytask.PickleNode`](../api/nodes_and_tasks.md#pytask.PickleNode) and returns the
-`pandas.DataFrame` whereas `data_catalog["csv"]` becomes a
+\[`pandas.DataFrame`\][] whereas `data_catalog["csv"]` becomes a
 [`pytask.PathNode`](../api/nodes_and_tasks.md#pytask.PathNode) and
 [`pytask.PNode.load`](../api/nodes_and_tasks.md#pytask.PNode.load) returns the path.