From 4d18171e5930d80c6fa374675f41a4680b1410b5 Mon Sep 17 00:00:00 2001
From: gnzng <damian@guenzing.de>
Date: Sun, 16 Nov 2025 11:00:33 -0600
Subject: [PATCH 1/2] docs: add instructions for building custom documentation

---
 README.md                 |  2 ++
 docs/build_custom_docs.md | 52 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 docs/build_custom_docs.md

diff --git a/README.md b/README.md
index 742b4725..8381ff10 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,8 @@ plt.show()
 
 Further documentation is found [here](https://cdtools-developers.github.io/cdtools/).
 
+Instructions for building custom documentation based on a specific version or commit can be found [here](https://github.com/cdtools-developers/cdtools/blob/master/docs/build_custom_docs.md).
+
 # Installation
 
 CDTools can be installed in several ways depending on your needs. For most users, installation from pypi is recommended. For developers or those who want the latest features, installation from source is available.
diff --git a/docs/build_custom_docs.md b/docs/build_custom_docs.md
new file mode 100644
index 00000000..51d39e22
--- /dev/null
+++ b/docs/build_custom_docs.md
@@ -0,0 +1,52 @@
+# Build custom docs
+
+This is a short description how to build custom documentation with `sphinx` based on the exact version (or even commit) you are using. 
+
+This requires a cloned version of `cdtools` from GitHub. See the installation guide for more information: 
+
+https://cdtools-developers.github.io/cdtools/installation.html#option-2-installation-from-source
+
+
+## Installation of Dependencies
+
+First, ensure you have all necessary dependencies installed. You can do this using [`uv`](https://github.com/astral-sh/uv):
+
+```sh
+uv pip install ."[docs]"
+```
+
+This will install your project along with the extra dependencies required for building the documentation.
+
+
+## Checkout the version or commit
+
+To ensure your documentation matches a specific version or commit of your codebase, use `git` to checkout the desired state. For example, to checkout a specific tag or commit:
+
+```sh
+git checkout <tag-or-commit-hash>
+```
+
+Replace `<tag-or-commit-hash>` with the version tag (e.g., `v1.2.3`) or the commit hash you want to use. This ensures the documentation is built for the exact code you are working with.
+
+## Building the Documentation
+
+To build the HTML documentation, run the following command from the root of your project:
+
+```sh
+uv run python -m sphinx -b html docs/source docs/_build/html/
+```
+
+This command tells Sphinx to build the documentation located in the `docs/source` directory and output the HTML files to `docs/_build/html/`.
+
+You can then open the generated HTML files in your browser to view the documentation.
+
+
+## Get back to the latest version of cdtools
+
+To return to the latest version of your code, use:
+
+```sh
+git checkout master
+```
+
+This will switch your working directory back to the latest development branch.
\ No newline at end of file

From 444b56b829cae8226d994c6c0303969d85a3766a Mon Sep 17 00:00:00 2001
From: gnzng <damian@guenzing.de>
Date: Sun, 16 Nov 2025 11:21:36 -0600
Subject: [PATCH 2/2] docs: update installation instructions for dependencies
 to include pip

---
 docs/build_custom_docs.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/build_custom_docs.md b/docs/build_custom_docs.md
index 51d39e22..f9f6f6f9 100644
--- a/docs/build_custom_docs.md
+++ b/docs/build_custom_docs.md
@@ -9,14 +9,19 @@ https://cdtools-developers.github.io/cdtools/installation.html#option-2-installa
 
 ## Installation of Dependencies
 
-First, ensure you have all necessary dependencies installed. You can do this using [`uv`](https://github.com/astral-sh/uv):
+First, ensure you have all necessary dependencies installed. You can do this using [`uv`](https://github.com/astral-sh/uv) or `pip`:
+
 
 ```sh
 uv pip install ."[docs]"
+# or, if you prefer pip:
+pip install ."[docs]"
 ```
 
 This will install your project along with the extra dependencies required for building the documentation.
 
+**Note:** `uv` is a fast Python package installer and resolver, serving as a drop-in replacement for `pip` with improved performance. You can use either `pip` or `uv` as shown above.
+
 
 ## Checkout the version or commit