Doc linklint fixups (#894)

# 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

@@ -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

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;
     }

doc/source/index.rst

@@ -6,7 +6,7 @@ MLOS Documentation
 .. image:: badges/coverage.svg
    :target: htmlcov/index.html
 
-`MLOS <source_tree_docs/index.html>`_ is a project to enable `autotuning <autoapi/mlos_core/index.html>`_ with `mlos_core <autoapi/mlos_core/index.html>`_ for systems via `automated benchmarking <autoapi/mlos_bench/index.html>`_ with `mlos_bench </autoapi/mlos_bench/index.html>`_ including managing the storage and `visualization <autoapi/mlos_viz/index.html>`_ of the results via `mlos_viz <autoapi/mlos_viz/index.html>`_.
+`MLOS <source_tree_docs/index.html>`_ is a project to enable `autotuning <autoapi/mlos_core/index.html>`_ with `mlos_core <autoapi/mlos_core/index.html>`_ for systems via `automated benchmarking <autoapi/mlos_bench/index.html>`_ with `mlos_bench <autoapi/mlos_bench/index.html>`_ including managing the storage and `visualization <autoapi/mlos_viz/index.html>`_ of the results via `mlos_viz <autoapi/mlos_viz/index.html>`_.
 
 Documentation is generated from both the `source tree markdown <source_tree_docs/index.html>`_ and the Python docstrings for each of the packages with navigation links on the side.
 

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
 <https://github.com/microsoft/MLOS/tree/main/mlos_bench/mlos_bench/config/>`_. Even
 so it may be useful to look at the source code to understand how those are
-interpretted.
+interpreted.
 
 Examples
 --------

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 <https://github.com/microsoft/MLOS/CONTRIBUTING.md>`_ 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 </mlos_bench.run.usage.html>`_ 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
   <https://github.com/microsoft/MLOS/tree/main/mlos_bench/mlos_bench/config/cli>`_
@@ -182,7 +182,7 @@
 
 :py:attr:`Globals <mlos_bench.config.schemas.config_schemas.ConfigSchema.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 </mlos_bench.run.usage.html>`_ for more details on those
-arguments.
+See `mlos_bench CLI usage <../../../mlos_bench.run.usage.html>`__ for more details
+on those arguments.
 
 Schema Definitions
 ++++++++++++++++++

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

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 </mlos_bench.run.usage.html>`_.
+See the current ``--help`` `output for details <../../../mlos_bench.run.usage.html>`_.
 
 See Also
 --------

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
         -------

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 <mlos_core.spaces.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()