Doxygen + index.md

[maxgolov]

trafficstars

We are publishing docs to GitHub pages. Currently there is no Index published, so there is no way to see the docs per se without knowing document name (which is hard to guess). While we work on OSS release, I think we need to add the following two things:

• Doxygen-generated API docs for C++ layer. Unfortunately I'm missing knowledge if we can push the docs on top of GitHub pages location, so that we don't store them in the repo. Need to explore how to get that set up.

• Index file - a reference guide with links to Doxygen API docs, plus the rest of documentation available.

[maxgolov]

@reyang @mkoscumb

I have the following proposal for Doxygen:

• generate doxygen docs from source using Doxygen in Markdown format
• check in the generated C++ API documents in /docs/api - which gets it auto-published to GitHub Pages
• on every commit - run the doxygen regenerate task, check if contents changed. If changed (e.g. method removed from API, which will result in API docs to change), fail the PR. And ask the user to manually re-generate the docs and check in the (regenerated) documentation change in the PR as well.

That way we can guarantee that:

• API changes are always documented
• methods are not randomly removed
• methods signatures are not changing without updating the Doxygen doc. We can add a write-up that explains the process.

What I don't exactly like is checking-in the generated Markdowns. BUT - it gives us an easy way to compare the API, based on Doxygen-generated API docs. Because we have checked in the (prev) API docs, we can detect if the (curr) directory becomes unclean: changes after rerun of the Doxygen generator on a new PR, should someone touch / adjust the public API - we'd easily flag that.

It'll be both:

• mandatory documentation.
• mandatory API stability check, that dev is clearly aware they are changing the API, documenting the API, and checking in the doc update for that change.

[reyang]

I've seen many GitHub projects publish docs to a separate branch (e.g. gh-pages) and set it as the branch for GitHub Pages.

My suggestion:

• A GH Action that generates the docs upon merge to master. The doc will be pushed to gh-pages branch.
• A GH Action that generates the docs on any PR to master, which checks the generated API doc against the published one from gh-pages branch.

[reyang]

We might also explore if there is public API checker for C++. For C# we've been following the .NET practice, for example this one will be enabled upon GA https://github.com/open-telemetry/opentelemetry-dotnet/pull/806.

[maxgolov]

Another alternate branch for pages also makes sense.. if we consider alternate branch for docs though, these are the pros and cons:

• big pro: no need to wait too long for CI to complete if we are only changing the docs.
• minor con: if somebody changes the API in the repo or want to add a document with their code change, they'd need to submit a corresponding change in the gh-pages branch (unless we automate the process of Doxygen run, then post updated doc, if change has been detected). It's sometimes helpful to see a markdown doc alongside with code change in one PR.

[lalitb]

Using separate gh-pages branch to publish the automatically generated Github pages seems to be most popular way of publishing C++ documents. Found something similar for travisCI, but it should be easy to automate it using github action.