html docs: please review and suggest!

[bwheelz36]

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.

[till-m]

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.

[bwheelz36]

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

[bwheelz36]

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

[till-m]

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.

[till-m]

IMO what we should do now, in order:

• Get Docstring overhaul #457 merged
• Get Poetry packaging #458 merged
• Modify the README
• Set up the PyPI releases as described in add github workflow to link github releases to pypi uploads #426
• Make a new release

after these QoL changes I'll have a look at #447 again

[bwheelz36]

@till-m - will close this now, thanks for the great work.