cdtools/docs/build_custom_docs.md

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.readthedocs.io/en/stable/installation.html#option-2-installation-from-source

Installation of Dependencies

First, ensure you have all necessary dependencies installed. You can do this using uv or pip:

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:

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:

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:

git checkout master

This will switch your working directory back to the latest development branch.