bayesian-optimization
html docs: please review and suggest!
Hi everyone (particularly recent contributors @till-m, @fmfn, @leandrobbraga)
I've set up the html docs to build through github workflows and build to a github page. every time there is a push to main branch, the docs will be rebuilt and place on the gh-pages branch. You can view the result here.
I haven't updated the repo description with this link yet because I think there's still some work to be done. I want to use this thread to keep track of the things we need to update:
- [ ] make sure image links are working
- [ ] review docstrings which are used to build code docs
- [ ] write a new notebook 'how it works' and remove a lot of this information from the readme.
Hi @bwheelz36,
I really like it!
Without having a detailed look, I think a good landing page that has pretty much the information of the README (Quick start, installation, etc.) would be really useful.
Also the documentation that I wrote for the constraint model is... not good. I will try and update it. Any chance you can link me to some guide about the syntax I can use within the documentation and how it will be rendered?
E: Maybe it would also be a good idea to officially adopt some docstring guidelines for this repository.
the documentation is directly rendered from the jupyter notebooks. So all you have to do is update the notebook and the docs will get rebuilt.
docstring guidelines sound like a good idea... I could maybe attempt to integrate something like pydocstyle into the tests. I suspect it would take a fair bit of work to get all docstrings up to some convention though. It seems like the ones I looked at are written in the numpy style? I might open a seperate issue on this topic...
Hey @till-m
I have added the webpage above to the repo's webpage tag:
Note that these docs are rebuilt directly from source anytime that the main branch changes.
If you give the OK, I would like to update the readme to make it a lot shorter, and basically say "please see docs".
Hey @bwheelz36,
If you give the OK, I would like to update the readme to make it a lot shorter, and basically say "please see docs".
I think this is a good idea.
FYI, what I've been doing currently is copy the README.md file to docsrc/ during building to integrate it into the sphinx docs. I think having the long-form of this README there still makes sense (as a sort of prolonged quick-start), though I agree that shortening the README here would be good. If it's fine with you, I would ask you to wait with this until I've merged the docs. We can then adjust which information is present where.
IMO what we should do now, in order:
- Get #457 merged
- Get #458 merged
- Modify the README
- Set up the PyPI releases as described in #426
- Make a new release
after these QoL changes I'll have a look at #447 again