[WIP] Sphinx based documentation

[betatim]

Fixes #428

Getting started with a documentation marathon.

• module doc strings
• adapt doc building so sphinx docs are pushed to github.io
• structure the API docs
• integrate example notebooks
• extend quickstart material
• add two paragraph summary of when skopt is the right tool

[betatim]

If you feel like contributing: the number one place help is needed is adding doc strings to the modules e.g. skopt/utils.py etc

[codecov-io]

Codecov Report

Merging #431 into master will increase coverage by 0.03%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #431      +/-   ##
==========================================
+ Coverage   86.46%   86.49%   +0.03%     
==========================================
  Files          22       22              
  Lines        1581     1585       +4     
==========================================
+ Hits         1367     1371       +4     
  Misses        214      214

Impacted Files	Coverage Δ
skopt/__init__.py	100% <ø> (ø)	⬆️
skopt/acquisition.py	95.95% <ø> (ø)	⬆️
skopt/optimizer/optimizer.py	93.71% <ø> (ø)	⬆️
skopt/searchcv.py	93.39% <ø> (ø)	⬆️
skopt/optimizer/gp.py	100% <ø> (ø)	⬆️
skopt/utils.py	98.51% <ø> (-0.02%)	⬇️
skopt/optimizer/gbrt.py	100% <ø> (ø)	⬆️
skopt/plots.py	8.33% <ø> (ø)	⬆️
skopt/space/space.py	92.72% <100%> (ø)	⬆️
skopt/callbacks.py	95.65% <100%> (ø)	⬆️
... and 1 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 47e3ae5...81eff29. Read the comment docs.

[MechCoder]

Thanks for starting this. How do I view the rendered documentation?

(https://707-54340642-gh.circle-artifacts.com/0/home/ubuntu/doc/skopt/notebooks/bayesian-optimization.html) corresponds to the original version?

[betatim]

At the moment by git checkouting this PR, pip install sphinx and cd docs && make html 😄

Figuring out how to make CircleCI build it is on the list of things to do

[MechCoder]

Hmm, I think it might work if you add the same lines to execute.sh under build_tools/circle

[betatim]

PRs to this PR welcome. I think this is the only way to overcome the problem of not merging this before it is complete and the fact that by myself I will never finish this.

[betatim]

I think we should try and convert our formatting to https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt mostly because there is a sphinx extension that can render this nicely and because it doesn't look horrible as plain text docstring. Open to other ideas.

For methods/functions/classes that are "simple" we can keep a plain doc string, but if we want to document parameters and return values we should adopt the numpy style.

[betatim]

Current snapshot: https://712-54340642-gh.circle-artifacts.com/0/tmp/circle-artifacts.Nzi5r9U/index.html

[betatim]

Alternative format that works well is the scikit-learn one.

[betatim]

@iaroslav-ai what do you think about trimming the BayesSearchCV doc string? It contains several references to sklearn classes that don't resolve at the moment. I'd try and shrink it a bit and put a note at the top: "For full details please refer t GridSearchCV in sklearn."

[iaroslav-ai]

@betatim would be really great if you would try to shrink it a bit, it is quite big indeed!

[betatim]

New snapshot: https://721-54340642-gh.circle-artifacts.com/0/tmp/circle-artifacts.kdXLWjd/index.html

(when did we add this much stuff to skopt? Always thought this was a cute little library ... 😄)

[MechCoder]

Thanks for your work! What thoughts do you have on integrating the example notebooks? sphinx-gallery might be a good option to do that.

[betatim]

Having sphinx-gallery was one of the reasons I started this move, so yes I think that is the way to go. Was reading the docs and now thinking it only works with python scripts not notebooks? There is also https://github.com/spatialaudio/nbsphinx which adds notebook support more widely (quick start and other introductory stuff could benefit from this).

Can you see a way to use notebooks with gallery?

[MechCoder]

nbsphinx seems pretty neat. Why not just use it?

[betatim]

nbsphinx seems pretty neat. Why not just use it?

Wanted to hear some opinions :) I think it isn't as widely used as sphinx-gallery so if there was a way to use gallery that would be better but seems there isn't. Will probably work on this tomorrow a bit. Slow progress.

[amueller]

hm my circle CI browser plugin fails to pick up on the build. I guess because the last one failed? Not sure :-/

[betatim]

Forgot to add the nbsphinx extension to the CI setup script.

Is there a tool (that works well) for converting our docstrings to numpydoc format? It isn't hard but pretty tedious (aka error prone) and feels like it is impossible to keep up with changes made elsewhere :)

In general what do people think about the layout/sections? Was thinking to add a few of the example notebooks as narrative docs after "quick start" (the what is bayes opt one and the BayesSearchCV one). Link to the rest as examples.