Add Documentation

[whytro]

I've added some documentation for py_osrm, using Sphinx, so it can be hosted on readthedocs.io. It will require subscribing the project on the readthedocs dashboard after the files are added, though it might require a few more additional file tinkering afterwards to get it working.

I have a test version up here, if you would like to see how it looks and add feedback: https://whytro-test.readthedocs.io/en/latest/

Some additions that need to be made here are:

• osrm-datastore/shared memory usage

[nilsnolde]

FWIW, I’d also try to put the API documentation in-code, ie as python docstrings. That way it’ll show up in the hosted docs and in IDEs. I didn’t use mkdocs for that yet, but I’m sure it’s an easy setup so it auto-extracts the docstrings and constructs the API docs/reference from it.

We probably don’t even need a docs folder. Simple usage can go into the README, more advanced stuff would be nicer in an interactive Jupiter notebook.

[whytro]

I can work with either. Most of the time spent in documentation writing was looking back at the code and checking syntax/checking references, rather than formatting, so a conversion from Sphinx to Markdown shouldn't take too long.

I'll go ahead and look into Mkdocs & Github Pages, so we can switch to that if preferred.

[nilsnolde]

Ok thanks:)

Github actions is lacking a bit of docs around publishing it. Easiest is to use „mkdocs gh-deploy —strict“ command (or so, on mobile right now) locally, that’ll create a branch „gh-pages“ which you can push to remote. Then in GH UI Settings we just need to point it there. And add a small workflow like this one: https://github.com/valhalla/valhalla/blob/master/.github/workflows/gh-pages.yml

[whytro]

I'm testing out autogenerated documentation from docstrings now, since I've gone back and added docstrings to the relevant bindings code. I've mainly used PEP 257 convention for now. I've had to shift it over to Google Format, since mkdocstrings requires one of three specific docstring formats, and the PEP 257 one isn't one of them afaik. It's taking a bit longer than expected since autogenerated documentation is a bit difficult to get looking clean I think.

As for the Jupyter Notebook, I liked the idea, but I thought it might be easier to do after the package is up on PyPI, and it should be easy to integrate into documentation after, since I already have the code examples prepared.

[nilsnolde]

Sounds good thanks @whytro ! Doesn’t have to look perfect either. Focus rather on maintainability/less complexity than UI.

[whytro]

I'll be closing this to create another PR for the Mkdocs documentation route!