Preserve autodoc shortcut links in docs

Author: tobiasraabe

.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)
+        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)
 -   repo: https://github.com/kynan/nbstripout
     rev: 0.9.1
     hooks:

docs/source/how_to_guides/capture_warnings.md

@@ -62,8 +62,9 @@ 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. \[`pandas.errors.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,7 @@
 # Hashing inputs of tasks
 
 Any input to a task function is parsed by pytask's nodes. For example,
-\[`pathlib.Path`\][]s are parsed by
+[`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,8 +35,9 @@ 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
 

docs/source/how_to_guides/remote_files.md

@@ -8,8 +8,8 @@ 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
+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,18 +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"
@@ -24,7 +24,8 @@ 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.
 
@@ -106,9 +107,9 @@ Here are some explanations.
 
 ## 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
+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.
 

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.
 

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,7 +122,8 @@ 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`\][] 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,12 +171,12 @@ path means the location is relative to the module of the data catalog.
 ```
 
 You can now use the data catalog as in the previous example and use the
-\[`pathlib.Path`\][] in the task.
+[`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
+    [`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).
@@ -218,6 +219,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.

docs/source/type_hints.md

@@ -6,8 +6,9 @@ information on the type of variables.
 Type hints can be used
 
 - by editors to provide better introspection into objects.
-- by tools like \[`mypy`\][] and [ty](https://github.com/astral-sh/ty) from Astral that
-    check your code given the variable types.
+- by tools like [`mypy`](https://mypy-lang.org/) and
+    [ty](https://github.com/astral-sh/ty) from Astral that check your code given the
+    variable types.
 - as additional documentation.
 
 pytask uses type hints as part of its interface.