Add Read The Docs

[noamzaks]

This migrates the existing Markdown documentation inside the doc folder to ReadTheDocs, which makes it more accessible and readible.

Creating a ReadTheDocs account should be free and then we can use the github actions to automatically build/deploy documentation and generate previews for PRs 🙂 Alternatively, we can compile the docs using GitHub Actions and then deploy to the KhronosGroup GitHub Pages.

Also adds a gitignore (for sphinx output and gh-pages output).

Generate the docs by running make html in the docs directory and perhaps running python3 -m http.server to host it locally.

Preview:

[chrisgearing]

This is really good. Ayal Zaks and I discuss who tough we are on code review, but I'm having difficulty finding even a suggestion for an improvement.

It highlights one problem - that we can't test our auto documentation build until after we commit!

We need to build a read the docs account befow landing and then update something presumably to make use of that. Or can we land and then update?

[noamzaks]

This is really good. Ayal Zaks and I discuss who tough we are on code review, but I'm having difficulty finding even a suggestion for an improvement.

Thanks 😊

It highlights one problem - that we can't test our auto documentation build until after we commit!

Yep, we can produce static HTML but I see no "simple" way to deploy it somewhere.

We need to build a read the docs account befow landing and then update something presumably to make use of that. Or can we land and then update?

There are two options:

• Build and deploy the static HTML pages ourselves, like is done with Doxygen.
• Create a ReadTheDocs account, in which case it can be entirely separate from Doxygen. It makes generating documentation previews for PRs easier, as far as I know. It should be noted that ReadTheDocs has a free tier which is somewhat limited and contains ads, so that's a consideration.

Of course we can do both. Currently the PR deploys the documentation near the doxygen pages. Using readthedocs will use a separate domain such as "opencl-ttl.readthedocs.io".