Add support for sphinx as a documentation generator

[pyohannes]

This PR adds support for sphinx as a documentation generator. sphinx was chosen as it is the framework of choice to publish documentation to https://readthedocs.org.

Under the hood it still uses doxygen to create reStructuredText files, which are then used by sphinx. So we don't need to change anything with our existing practices for API documentation.

Currently this includes a root project in docs/public, which can link specific subprojects. Currently the only subproject linked is the API documentation in api/docs.

This is how it looks on readthedocs: https://opentelemetry-c-api.readthedocs.io/en/latest/

When this PR is approved, I will set up a readthedocs project based on this repository, the above is just a placeholder to show how the final result will look like.

[codecov]

Codecov Report

Merging #595 (d2ee0ba) into main (71d5b1d) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #595   +/-   ##
=======================================
  Coverage   94.34%   94.34%           
=======================================
  Files         189      189           
  Lines        8949     8949           
=======================================
  Hits         8443     8443           
  Misses        506      506           

[ThomsonTan]

Update this to 0.2.0?

[pyohannes]

Good point, I fixed it.

[lalitb]

Do we need to add sphinx-build too in install dependencies, or the plugins installation will take care of it automatically ?

[lalitb]

Thanks for adding this. LGTM. Sphinx looks really cool - much better docs from doxygen genear html. Couple of things:

1. Hopefully it should be possible to extend this documentation further to include member functions as part of class documentation. Ex, to add member functions for Tracer class: https://opentelemetry-c-api.readthedocs.io/en/latest/otel_api/classopentelemetry_1_1trace_1_1Span.html#exhale-class-classopentelemetry-1-1trace-1-1Span

2. As part of release process, do we need to invoke some webhook to let readthedocs know about the new changes, so that it can regenerate the doc. In case this is not planned as part of readthedocs setup, we can have a github issue? I do plan to work on github action for new releases, and can take care of this.

[pyohannes]

Hopefully it should be possible to extend this documentation further to include member functions as part of class documentation.

This should already be there. I'll check why it doesn't show up.

[pyohannes]

As part of release process, do we need to invoke some webhook to let readthedocs know about the new changes, so that it can regenerate the doc.

The readthedocs build automatically kicks off when we push to registered branches. Branches are registered on the readthedocs site, all the documentation building happens in an environment provided by readthedocs, so we do not need a GitHub action on our side.

What we would need to do on our side: for every new release we will need to register the release/branch on readthedocs. I assume we will have main registered for the version latest.