`make doc` fixups to address CI issues

[bpkroth]

trafficstars

Pull Request

Title

Documentation generation fixups to address recent CI issues.

---

Description

• 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 and autodoc
• [ ] Update overview.rst to follow suite
  • [ ] Alternatively, move overview text into the docstrings and just use autoapi for everything.
• [ ] Update mlos_bench.run help usage

---

Type of Change

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

---

Testing

• Passes CI

---

[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

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