Add Sphinx documentation

[jonathf]

@jcoupey, I made a first pass at gathering the Python documentation together now at #114. Do you have a preference as to where we should host it?

I see the following alternatives as viable:

• A subpage under the Vroom domain like e.g. http://vroom-project.org/pyvroom
• Github pages: https://VROOM-Project.github.io/pyvroom
• Read-the-docs (with ads): https://pyvroom.rtd.org/

[jcoupey]

Thanks for asking, I'd be in favor of using the vroom-project domain as main entry point. I can take care of uploading/updating the docs there whenever needed. What would the publishing process look like?

[jonathf]

Building docs is done with a single build command that generates an html folder ready for publication.

My preference is to have something automatic set up in cicd.

[jcoupey]

If the build is done on CI, I could automatically rsync that to http://vroom-project.org/pyvroom, but not sure how we'd store the CI build though? What I could do easily is setup a cron job to push + build daily on the machine serving the website.

[jonathf]

If you want to pull instead of push changes then I suggest we store CI output in an intermediate dedicated repo like pyvroom-docs. pyvroom will autmatically push changes to this repo and your cron can then pull from this repo asyncronously.

[jcoupey]

Sure, sounds like a good process. I actually wrote "push" in my previous message but meant "pull"...

[jonathf]

Great. Do you mind making the doc repo and adding a depoloy token here with push rights?

[jcoupey]

@jonathf just created the pyvroom-docs repo and added you as a maintainer. Does this gives your rights for the token thing?

[jonathf]

Unfortunatly no.

A deploy key needs to be added to pyvroom-docs with write access. The same key needs to be added to pyvroom as a repository secret.

• Here is a guide for deploying keys
• Adding secrets is done under Settings, Secrets and variables and Actions.

With this in place, I can do the rest.

[jcoupey]

Thanks for the pointers. I just created a dedicated ssh key, added the public key as a deploy key with write access in pyvroom-docs and set the private key as SSH_PRIVATE_KEY secret in this repo. Let me know if that works!

[jonathf]

Excellent! I'll take a look at it when I have some more time to spare.