Merged PR 403: Minor doc tweaks and cleanup

- ignore some more auto generated files
- don't need regular users to have to build the docs
- tweaks to the docs
- install some modules necessary for vscode extensions to lint check rst

.gitignore

@@ -140,6 +140,8 @@ cython_debug/
 # vim swap files
 .*.swp
 
+junit/test-results.xml
+
 .conda-env.build-stamp
 .conda-env.*.build-stamp
 .doc-prereqs.build-stamp

Makefile

@@ -4,7 +4,7 @@ ENV_YML := conda-envs/${CONDA_DEFAULT_ENV}.yml
 PYTHON_FILES := $(shell find mlos_core/ -type f -name '*.py' 2>/dev/null)
 
 .PHONY: all
-all: check test dist doc
+all: check test dist # doc
 
 .PHONY: conda-env
 conda-env: .conda-env.${CONDA_DEFAULT_ENV}.build-stamp

README.md

@@ -6,8 +6,9 @@ It is intended to provide a simplified, easier to consume (e.g. via `pip`), with
 
 - describe a space of context, parameters, their ranges, constraints, etc. and result objectives
 - an "optimizer" service abstraction (e.g. `register()` and `suggest()`) so we can easily swap out different implementations methods of searching (e.g. random, BO, etc.)
+- provide some helpers for automating optimization experiment runner loops and data collection
 
-For both design requires intend to reuse as much OSS libraries as possible.
+For these design requirements we intend to reuse as much from existing OSS libraries as possible.
 
 ## Getting Started
 
@@ -52,6 +53,6 @@ For both design requires intend to reuse as much OSS libraries as possible.
 
 ## See Also
 
-- <https://aka.ms/mlos-core/docs>
-- <https://aka.ms/mlos-core/src>
-- [MlosCoreApiDesign.docx](https://microsoft.sharepoint.com/:w:/t/CISLGSL/ESAS3G9q4P5Hoult9uqTfB4B3xh2v6yUfp3YNgIvoyR_IA?e=B6klWZ)
+- API and Examples Documentation: <https://aka.ms/mlos-core/docs>
+- Source Code Repository: <https://aka.ms/mlos-core/src>
+- Initial Design Discussion Doc: [MlosCoreApiDesign.docx](https://microsoft.sharepoint.com/:w:/t/CISLGSL/ESAS3G9q4P5Hoult9uqTfB4B3xh2v6yUfp3YNgIvoyR_IA?e=B6klWZ)

doc/requirements.txt

@@ -2,3 +2,6 @@ sphinx
 nbsphinx
 numpydoc
 sphinx-rtd-theme
+
+doc8
+rstcheck

doc/source/.gitignore

@@ -1 +1,2 @@
 api/
+generated/

doc/source/index.rst

@@ -7,8 +7,9 @@ It is intended to provide a simplified, easier to consume (e.g. via ``pip``), wi
 
 - describe a space of context, parameters, their ranges, constraints, etc. and result objectives
 - an "optimizer" service abstraction (e.g. ``register()`` and ``suggest()``) so we can easily swap out different implementations methods of searching (e.g. random, BO, etc.)
+- provide some helpers for automating optimization experiment runner loops and data collection
 
-For both design requires intend to reuse as much OSS libraries as possible.
+For these design requirements we intend to reuse as much from existing OSS libraries as possible.
 
 .. toctree::
    :hidden:
@@ -23,4 +24,4 @@ For both design requires intend to reuse as much OSS libraries as possible.
    :hidden:
    :caption: Examples
 
-   auto_examples/index
+   auto_examples/index