Merge pull request #61 from gnzng/customdocs

[docs] Adding instruction to build custom documentation based on version or commit hashes

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.

docs/build_custom_docs.md

@@ -0,0 +1,57 @@
+# 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) 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
+
+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.