Merge pull request #131 from martius-lab/fkloss/push-tnnxsutyxsqn

docs: Move to RTD - Update links and remove workflow

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Changed
+- Moved documentation from GitHub Pages to Read the Docs.  This allows to more easily
+  manage docs for different versions.
+
 ## [3.0.0] - 2024-08-19
 
 ### Changed

README.md

@@ -31,23 +31,13 @@ If you encounter any bugs or have suggestions for improvements, please submit an
 pip install "cluster_utils[runner]"
 ```
 
-See [documentation](https://martius-lab.github.io/cluster_utils/installation.html) for more details.
+See [documentation](#documentation) for more details.
 
 ## Documentation
 
-The documentation is hosted at https://martius-lab.github.io/cluster_utils.
+- Documentation of last stable release: https://cluster-utils.readthedocs.io/stable/
+- Documentation of current development version: https://cluster-utils.readthedocs.io/latest/
 
-You can also build the documentation locally with the following commands:
-
-```bash
-git clone https://github.com/martius-lab/cluster_utils.git
-cd cluster_utils
-# install package with the additional dependencies needed to build the documentation
-pip install ".[docs]"
-cd docs/
-make html  # build documentation
-```
-When the build is finished, open ``docs/_build/html/index.html`` with the browser of your choice.
 
 ## Quick Start
 
@@ -116,11 +106,4 @@ The simplest way to specify your Python environment is to activate it (using vir
 The jobs will automatically inherit this environment.
 A caveat of this approach is that if you *installed your local package in the environment*, this package *might override* the repository cluster_utils clones using git, i.e. you are not using a clean clone of your project.
 
-There are multiple options to further customize the environment in the `environment_setup` configuration section, see [the documentation](https://martius-lab.github.io/cluster_utils/configuration.html).
-
-### Further Documentation Links
-
-- [Configuration for Slurm & Condor Cluster Systems](https://martius-lab.github.io/cluster_utils/configuration.html#cluster-requirements)
-- [Hyperparameter Optimization Settings](https://martius-lab.github.io/cluster_utils/configuration.html#optimizer-settings)
-- [Hyperparameter Optimization Mindset and Rules of Thumb](https://martius-lab.github.io/cluster_utils/usage_mindset_and_rule_of_thumb.html)
-- [Development](https://martius-lab.github.io/cluster_utils/setup_devel_env.html)
+There are multiple options to further customize the environment in the `environment_setup` configuration section, see [the documentation](https://cluster-utils.readthedocs.io/stable/configuration.html).

docs/conf.py

@@ -104,7 +104,7 @@
 
 # Material theme options
 html_theme_options = {
-    "site_url": "https://martius-lab.github.io/cluster_utils",
+    "site_url": "https://cluster-utils.readthedocs.io/",
     "repo_url": "https://github.com/martius-lab/cluster_utils",
     "palette": {"primary": "blue-grey", "accent": "orange"},
     "globaltoc_includehidden": False,

docs/setup_devel_env.rst

@@ -109,3 +109,28 @@ In fact, this is useful to make sure a commit runs through without any checks
 failing.
 
 
+Build Documentation
+===================
+
+To build the documentation locally, first install the documentation requirements (using
+the "docs" extra options):
+
+.. code-block:: sh
+
+    pip install -e ".[docs]"
+
+To build the docs, run the following command from the root of the repository:
+
+.. code-block:: sh
+
+    make -C docs/ html
+
+When the build is finished, open ``docs/_build/html/index.html`` with the browser of
+your choice.
+
+To enable "nitpicky" mode of Sphinx (warns about all missing references, recommended to
+always set during development):
+
+.. code-block:: sh
+
+   make -C docs/ SPHINXOPTS=-n html

pyproject.toml

@@ -43,7 +43,7 @@ dependencies = [
 # package root.
 
 [project.urls]
-Documentation = "https://martius-lab.github.io/cluster_utils"
+Documentation = "https://cluster-utils.readthedocs.io/"
 Repository = "https://github.com/martius-lab/cluster_utils"
 Issues = "https://github.com/martius-lab/cluster_utils/issues"