From 3faaa56d2fc92b53dc627c443440332dd77cadaa Mon Sep 17 00:00:00 2001 From: Brian Kroth Date: Sat, 7 Dec 2024 14:08:18 -0600 Subject: [PATCH] Doc linklint fixups (#894) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Pull Request ## Title Doc linklint fixups --- ## Description GithubPages serves our docs out of a `/MLOS` path, but previously we checked things out of `/` using an Nginx docker container. This PR changes the Nginx docker container used for testing to also serve paths out of `/MLOS` and fixes the broken links found from that. - [x] Adjust Nginx to serve from `/MLOS` like Github pages. - [x] Fix linklint errors found from that - [x] spelling - See #891 --- ## Type of Change - 📝 Documentation update --- ## Testing - Existing CI (which includes docstring and some link lint checks) --- --- Makefile | 17 ++++++++++------- doc/nginx-default.conf | 8 +++++--- doc/source/index.rst | 2 +- mlos_bench/mlos_bench/__init__.py | 8 ++++---- mlos_bench/mlos_bench/config/__init__.py | 18 +++++++++--------- mlos_bench/mlos_bench/environments/__init__.py | 4 ++-- mlos_bench/mlos_bench/run.py | 2 +- mlos_bench/mlos_bench/tunables/tunable.py | 2 +- mlos_core/mlos_core/__init__.py | 6 +++--- 9 files changed, 36 insertions(+), 31 deletions(-) diff --git a/Makefile b/Makefile index 56ad5b0396a..cb5ed8efb5a 100644 --- a/Makefile +++ b/Makefile @@ -754,16 +754,19 @@ else linklint-doc: build/linklint-doc.build-stamp endif -build/linklint-doc.build-stamp: doc/build/html/index.html doc/build/html/htmlcov/index.html build/check-doc.build-stamp +.PHONY: nginx_port_env +nginx_port_env: @echo "Starting nginx docker container for serving docs." ./doc/nginx-docker.sh restart - docker port mlos-doc-nginx nginx_port=`docker port mlos-doc-nginx | grep 0.0.0.0:8080 | cut -d/ -f1` \ - && echo nginx_port=$${nginx_port} \ - && set -x \ - && docker exec mlos-doc-nginx curl -sSf http://localhost:$${nginx_port}/index.html >/dev/null - @echo "Running linklint on the docs." - docker exec mlos-doc-nginx linklint -net -redirect -root /doc/build/html/ /@ -error -warn > doc/build/linklint.out 2>&1 + && echo nginx_port=$${nginx_port} > doc/build/nginx_port.env + +build/linklint-doc.build-stamp: nginx_port=$(shell cat doc/build/nginx_port.env | cut -d= -f2 | egrep -x '[0-9]+') +build/linklint-doc.build-stamp: doc/build/html/index.html doc/build/html/htmlcov/index.html build/check-doc.build-stamp nginx_port_env + @echo "Running linklint on the docs at http://localhost:${nginx_port}/MLOS/ ..." + docker exec mlos-doc-nginx curl -sSf http://localhost:${nginx_port}/MLOS/index.html >/dev/null + docker exec mlos-doc-nginx linklint -root /doc/build/html/ /@ -error -warn > doc/build/linklint.out 2>&1 + docker exec mlos-doc-nginx linklint -net -redirect -host localhost:${nginx_port} /MLOS/@ -http -error -warn > doc/build/linklint.out 2>&1 @if cat doc/build/linklint.out | grep -e ^ERROR -e ^WARN | grep -v 'missing named anchors' | grep -q .; then \ echo "Found errors in the documentation:"; cat doc/build/linklint.out; exit 1; \ fi diff --git a/doc/nginx-default.conf b/doc/nginx-default.conf index ab5605c3441..eb401a92a79 100644 --- a/doc/nginx-default.conf +++ b/doc/nginx-default.conf @@ -5,10 +5,12 @@ server { #access_log /var/log/nginx/host.access.log main; + absolute_redirect off; + rewrite ^/$ /MLOS/ redirect; + # Expects ./doc to be mapped to /doc in the nginx container. - location / { - #root /usr/share/nginx/html; - root /doc/build/html/; + location /MLOS/ { + alias /doc/build/html/; autoindex on; index index.html index.htm; } diff --git a/doc/source/index.rst b/doc/source/index.rst index 8a1d6d919b6..c31aeb4b633 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,7 +6,7 @@ MLOS Documentation .. image:: badges/coverage.svg :target: htmlcov/index.html -`MLOS `_ is a project to enable `autotuning `_ with `mlos_core `_ for systems via `automated benchmarking `_ with `mlos_bench `_ including managing the storage and `visualization `_ of the results via `mlos_viz `_. +`MLOS `_ is a project to enable `autotuning `_ with `mlos_core `_ for systems via `automated benchmarking `_ with `mlos_bench `_ including managing the storage and `visualization `_ of the results via `mlos_viz `_. Documentation is generated from both the `source tree markdown `_ and the Python docstrings for each of the packages with navigation links on the side. diff --git a/mlos_bench/mlos_bench/__init__.py b/mlos_bench/mlos_bench/__init__.py index 79879a2ec95..9986cbc7824 100644 --- a/mlos_bench/mlos_bench/__init__.py +++ b/mlos_bench/mlos_bench/__init__.py @@ -19,7 +19,7 @@ It is intended to be used with :py:mod:`mlos_core` via :py:class:`~mlos_bench.optimizers.mlos_core_optimizer.MlosCoreOptimizer` to help -navigate complex parameter spaces more effeciently, though other +navigate complex parameter spaces more efficiently, though other :py:mod:`~mlos_bench.optimizers` are also available to help customize the search process easily by simply swapping out the :py:class:`~mlos_bench.optimizers.base_optimizer.Optimizer` class in the associated @@ -32,10 +32,10 @@ ^^^^^ The overall goal of the MLOS project is to enable *reproducible* and *trackable* -benchmarking and *effecient* autotuning for systems software. +benchmarking and *efficient* autotuning for systems software. In this, automation of the benchmarking process is a key component that -``mlos_bench`` seaks to enable. +``mlos_bench`` seeks to enable. Interaction ^^^^^^^^^^^ @@ -136,7 +136,7 @@ interactions with the package will be through the `json configs `_. Even so it may be useful to look at the source code to understand how those are -interpretted. +interpreted. Examples -------- diff --git a/mlos_bench/mlos_bench/config/__init__.py b/mlos_bench/mlos_bench/config/__init__.py index 17606aba629..4ee6e9aafa3 100644 --- a/mlos_bench/mlos_bench/config/__init__.py +++ b/mlos_bench/mlos_bench/config/__init__.py @@ -3,7 +3,7 @@ # Licensed under the MIT License. # """ -A module for and documentation about the structure and mangement of json configs, their +A module for and documentation about the structure and management of json configs, their schemas and validation for various components of MLOS. .. contents:: Table of Contents @@ -46,7 +46,7 @@ do that for the next set. Hence, they are usually split into several files and directory structures. -We attempt to provide some examples and reuable templates in the core ``mlos_bench`` +We attempt to provide some examples and reusable templates in the core ``mlos_bench`` package, but users are encouraged to create their own configs as needed, or to `submit PRs or Issues `_ to add additional ones. @@ -65,7 +65,7 @@ :py:class:`~mlos_bench.environments.script_env.ScriptEnv`) and :py:mod:`~mlos_bench.tunables`. - There is usally one *root* environment that chains the others together to build + There is usually one *root* environment that chains the others together to build a full experiment (e.g., via :py:class:`~mlos_bench.environments.composite_env.CompositeEnv` and the ``include_children`` field). @@ -101,7 +101,7 @@ - ``services/``: Contains the configs for :py:mod:`mlos_bench.services`. - In general servies can simply be referenced in the CLI config's ``services`` + In general services can simply be referenced in the CLI config's ``services`` field, though sometimes additional settings are required, possibly provided by an additional ``globals`` config in the CLI config. @@ -169,7 +169,7 @@ Notes ----- -- See `mlos_bench CLI usage `_ for more details on the +- See `mlos_bench CLI usage <../../../mlos_bench.run.usage.html>`_ for more details on the CLI arguments. - See `mlos_bench/config/cli `_ @@ -182,7 +182,7 @@ :py:attr:`Globals ` are basically just key-value variables that can be used in other configs using -``$variable`` substituion via the +``$variable`` substitution via the :py:meth:`~mlos_bench.dict_templater.DictTemplater.expand_vars` method. For instance: @@ -199,7 +199,7 @@ "location": "eastus", } -There are additional details about variable propogation in the +There are additional details about variable propagation in the :py:mod:`mlos_bench.environments` module. Well Known Variables @@ -322,8 +322,8 @@ The typical entrypoint is a CLI config which references other configs, especially the base Environment config, Services, Optimizer, and Storage. -See `mlos_bench CLI usage `_ for more details on those -arguments. +See `mlos_bench CLI usage <../../../mlos_bench.run.usage.html>`__ for more details +on those arguments. Schema Definitions ++++++++++++++++++ diff --git a/mlos_bench/mlos_bench/environments/__init__.py b/mlos_bench/mlos_bench/environments/__init__.py index 9ba6c9a161a..f75806d021b 100644 --- a/mlos_bench/mlos_bench/environments/__init__.py +++ b/mlos_bench/mlos_bench/environments/__init__.py @@ -86,9 +86,9 @@ used in different settings (e.g., local machine, SSH accessible machine, Azure VM, etc.) without having to change the Environment config. -Variable Propogation +Variable Propagation ++++++++++++++++++++ -TODO: Document how variable propogation works in the script environments using +TODO: Document how variable propagation works in the script environments using required_args, const_args, etc. Examples diff --git a/mlos_bench/mlos_bench/run.py b/mlos_bench/mlos_bench/run.py index cc3cf60b8f6..61d8cc26ce0 100755 --- a/mlos_bench/mlos_bench/run.py +++ b/mlos_bench/mlos_bench/run.py @@ -8,7 +8,7 @@ Note: this script is also available as a CLI tool via ``pip`` under the name ``mlos_bench``. -See the current ``--help`` `output for details `_. +See the current ``--help`` `output for details <../../../mlos_bench.run.usage.html>`_. See Also -------- diff --git a/mlos_bench/mlos_bench/tunables/tunable.py b/mlos_bench/mlos_bench/tunables/tunable.py index f6452bffcfe..0b563557b32 100644 --- a/mlos_bench/mlos_bench/tunables/tunable.py +++ b/mlos_bench/mlos_bench/tunables/tunable.py @@ -607,7 +607,7 @@ def quantization_bins(self) -> Optional[int]: @property def quantized_values(self) -> Optional[Union[Iterable[int], Iterable[float]]]: """ - Get a sequence of quanitized values for this tunable. + Get a sequence of quantized values for this tunable. Returns ------- diff --git a/mlos_core/mlos_core/__init__.py b/mlos_core/mlos_core/__init__.py index de55b3ec2b4..cb19057a7d3 100644 --- a/mlos_core/mlos_core/__init__.py +++ b/mlos_core/mlos_core/__init__.py @@ -87,7 +87,7 @@ One example is for automatic search space reduction (e.g., using :py:mod:`~mlos_core.spaces.adapters.llamatune`) in order to try and improve search -effeciency (see the :py:mod:`~mlos_core.spaces.adapters.llamatune` and +efficiency (see the :py:mod:`~mlos_core.spaces.adapters.llamatune` and :py:mod:`space adapters ` modules for additional documentation.) @@ -130,14 +130,14 @@ >>> _ = cs.add(UniformIntegerHyperparameter("x", lower=0, upper=10)) >>> # Create a new optimizer instance using the SMAC optimizer. >>> opt_args = {"seed": 1234, "max_trials": 100} ->>> space_adpaters_kwargs = {} # no additional args for this example +>>> space_adapters_kwargs = {} # no additional args for this example >>> opt = OptimizerFactory.create( ... parameter_space=cs, ... optimization_targets=["y"], ... optimizer_type=OptimizerType.SMAC, # or FLAML, etc. ... optimizer_kwargs=opt_args, ... space_adapter_type=SpaceAdapterType.IDENTITY, # or LLAMATUNE -... space_adapter_kwargs=space_adpaters_kwargs, +... space_adapter_kwargs=space_adapters_kwargs, ... ) >>> # Get a new configuration suggestion. >>> suggestion = opt.suggest()