Minimal docs

AUTHORS.md

@@ -3,7 +3,7 @@
 
 ## Development Lead
 
-AutoML Hannover <automl@ai.uni-hannover.de>
+Theresa Eimer <t.eimer@ai.uni-hannover.de>
 
 ## Contributors
 

Makefile

@@ -26,7 +26,7 @@ BROWSER := python -c "$$BROWSER_PYSCRIPT"
 help:
 	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
 
-clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
+clean: clean-build clean-pyc clean-test clean-docs## remove all build, test, coverage and Python artifacts
 
 clean-build: ## remove build artifacts
 	rm -fr build/
@@ -46,6 +46,10 @@ clean-test: ## remove test and coverage artifacts
 	rm -f .coverage
 	rm -fr htmlcov/
 	rm -fr .pytest_cache
+
+clean-docs: ## remove docs artifacts
+	cd docs && make clean
+
 ruff: ## run ruff as a formatter
 	python -m ruff format hydra_plugins
 	python -m ruff --silent --exit-zero --no-cache --fix hydra_plugins
@@ -67,10 +71,10 @@ coverage: ## check code coverage quickly with the default Python
 docs: ## generate Sphinx HTML documentation, including API docs
 	rm -f docs/hypersweeper.rst
 	rm -f docs/modules.rst
-	sphinx-apidoc -o docs/ hypersweeper
+	sphinx-apidoc -o docs/ hydra_plugins
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
-	$(BROWSER) docs/_build/html/index.html
+
 bump-version: ## bump the version -- add current version number and kind of upgrade (minor, major, patch) as arguments
 	bump-my-version bump --current-version
 

docs/Makefile

@@ -0,0 +1,32 @@
+SPHINXBUILD = sphinx-build
+BUILDDIR = build
+SPHINXOPTS =
+ALLSPHINXOPTS = $(SPHINXOPTS) .
+
+.PHONY: clean buildapi linkcheck html docs html-noexamples
+
+clean:
+		rm -rf $(BUILDDIR)
+		rm -rf examples
+		rm -rf hyper*.rst
+
+linkcheck:
+		SPHINX_GALLERY_PLOT=False $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+		@echo
+		@echo "Link check complete; look for any errors in the above output or in $(BUILDDIR)/linkcheck/output.txt."
+
+linkcheck:
+		SPHINX_GALLERY_PLOT=False $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+		@echo
+		@echo "Link check complete; look for any errors in the above output or in $(BUILDDIR)/linkcheck/output.txt."
+html:
+		$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+		@echo
+		@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+html-noexamples:
+		SPHINX_GALLERY_PLOT=False $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
+		@echo
+		@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+docs: html linkcheck

docs/conf.py

@@ -0,0 +1,36 @@
+
+import os, sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+import automl_sphinx_theme  # Must come after the path injection above
+
+
+options = {
+    "copyright": copyright,
+    "author": "Theresa Eimer",
+    "version": "0.1",
+    "versions": {
+        f"v0.1 (stable)": "#",
+    },
+    "name": "Hypersweeper",
+    "html_theme_options": {
+        "github_url": "https://github.com/automl/automl_sphinx_theme",
+        "twitter_url": "https://twitter.com/automl_org?lang=de",
+    },
+    # this is here to exclude the examples gallery since they are not documented
+    "extensions": [
+        "myst_parser",
+        "sphinx.ext.autodoc",
+        "sphinx.ext.viewcode",
+        "sphinx.ext.napoleon",  # Enables to understand NumPy docstring
+        # "numpydoc",
+        "sphinx.ext.autosummary",
+        "sphinx.ext.autosectionlabel",
+        "sphinx_autodoc_typehints",
+        "sphinx.ext.doctest",
+    ],
+}
+
+# Import conf.py from the automl theme
+automl_sphinx_theme.set_options(globals(), options)

docs/index.rst

@@ -0,0 +1,41 @@
+
+Hypersweeper
+==================================================
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   source/getting_started
+   source/adding_new_optimizers
+   modules
+   source/cite
+
+Welcome to the documentation of Hypersweeper, a hydra interface for ask-and-tell hyperparameter optimization.
+Hypersweeper uses Hydra to let you parallelize hyperparameter optimization across multiple GPUs and CPUs.
+You don't need to worry about compability with your favorite optimizer since it works with any ask-and-tell interface with only minimal coding.
+We also include a range of optimizers that you can use out of the box.
+
+
+How Can You Use the Hypersweeper?
+---------------------------------
+
+To use Hypersweeper, you first need to define your target function, i.e. whatever you want to tune, using Hydra as a command line interface.
+You should also return the performance value of the target function.
+TODO: example
+To then do HPO using the Hypersweeper, simply override the default Hydra sweeper with the Hypersweeper variation of your choice.
+TODO: example
+To parallelize on a cluster, you should additionally override the launcher to whichever one you need.
+TODO: example
+And of course you also need a search space, for example something like this:
+TODO: example
+This is the final config for this simple case:
+TODO: example
+Finally, you can run your optimization using the following command:
+TODO: example
+
+Contact
+-------
+
+Hypersweeper is developed by `<https://www.automl.org/>`_.
+If you want to contribute or found an issue please visit our github page `<https://github.com/automl-private/hypersweeper>`_.

docs/modules.rst

@@ -1,6 +1,12 @@
-hypersweeper
-============
+hydra_plugins
+=============
 
 .. toctree::
    :maxdepth: 4
 
+   hyper_carp_s
+   hyper_hebo
+   hyper_pbt
+   hyper_rs
+   hyper_smac
+   hypersweeper

docs/source/cite.rst

@@ -0,0 +1,17 @@
+.. |br| raw:: html
+
+    <br />
+
+Citing Hypersweeper
+====================
+
+If you use the Hypersweeper in your research, please cite us (in addition to the optimizer you used) with the following Bibtex entry:
+
+.. code:: text
+
+    @misc{hypersweeper,
+      author       = {Theresa Eimer and Carolin Benjamins},
+      title        = {Hypersweeper},
+      howpublished = {https://github.com/automl-private/hypersweeper},
+      year         = {2024},
+    }