Rework documentation generation

[bpkroth]

Pull Request

Title

Documentation generation rework.

---

Description

This PR does an initial revamp of the way we generate and write documentation.

The goal is to simplify the generation process a bit by removing some hacks but also enable more strict checking of the documentation produced so that links resolve properly so that it is easier to navigate.

This PR is mostly the mechanics and the associated fixups to do that.
Future PRs can handle additional documentation in docstrings.

Below is a more detailed description of some of the changes.

• Apply black and pylint to the sphinx conf.py
• Treat sphinx warnings as errors
• Reorg doc generation using autoapi to handle cross referencing warnings and drop use of sphinx-apidoc
• Update overview.rst to follow suite
  • Alternatively, move overview text into the docstrings and "just" use autoapi for everything.
    • Use :py:func:, :py:class:, :py:meth:, :py:mod:, etc. to cross reference functions and classes in the docstrings.
    • Add napolean to parse numpydoc style docstrings
      (previous numpydoc method was incomplete)
    • Use intersphinx and nitpick to check (or ignore where not possible) all internal and most external cross references to ensure good code navigation
      • Fixup all broken references by either adding fully qualified types in docstrings or in the imports.
      • Ignore type aliase for for now
        (documented bug, will address in a future PR)
    • Add a few high level examples in docstrings.
      • May need from_config_string style loaders to help with this.
    • Add doctest to pytest to validate examples.
• Update mlos_bench.run help usage output to an rst file and link that into the man table of contents tree in the output.

---

Type of Change

• 🛠️ Bug fix
• 📝 Documentation update
• 🧪 Tests

---

Testing

• Adds additional checks and linting.

• Must pass CI

• Manual testing as follows:

  # SKIP_COVERAGE tweak is optional - just avoids a `pytest` job dependency
  make SKIP_COVERAGE=true doc
  ./doc/nginx-docker.sh restart

  Browse to http://localhost:8080 and check the results.

---

Additional Notes

Future PRs can add additional documentation strings for the mlos_bench classes including examples.

In particular

• mlos_bench.optimizers
• mlos_bench.services

[bpkroth]

@motus this is the wip PR I was mentioning. I think moving more of our docs directly into docstrings and making use of sphinx-autoapi should help make the Github Pages version of the documentation a little bit easier to consume without having to switch back and forth with the source code markdown quite so often.

I'd like for us to add more and more examples and explanations of what and how to think about the different configs, environments, etc. there with references back to the markdown files in the source code as necessary.

Separately, we should probably add Discussions or Wiki pages or something here to allow more people to ask and answer questions about how to do things and get started.

[bpkroth]

Note to self:
https://www.sphinx-doc.org/en/master/usage/domains/python.html#python-xref-roles

[motus]

Did the first pass, left some nitpicks. My biggest question so far is the mismatch between the imports and the way we reference to them in docstrings. Please see my comments re: datetime.datetime, pandas vs. pd, ConfigSpace.ConfigurationSpace, tempfile and such

[bpkroth]

Did the first pass, left some nitpicks. My biggest question so far is the mismatch between the imports and the way we reference to them in docstrings. Please see my comments re: datetime.datetime, pandas vs. pd, ConfigSpace.ConfigurationSpace, tempfile and such

Yeah, I fought with that a bit, but gave up in the interest of getting something working.

For some reason it appears to correctly resolve from the imports most of the things, but not all of them.

Rather than fight with it or disable the nitpick checking (since I think that's valuable for catching broken reference links to make sure our doc navigation works), I just changed the ones that complained to use fully qualified names.