Open maxgolov opened 3 years ago
@reyang @mkoscumb
I have the following proposal for Doxygen:
/docs/api
- which gets it auto-published to GitHub PagesThat way we can guarantee that:
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:
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:
gh-pages
branch.gh-pages
branch.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.
Another alternate branch for pages also makes sense.. if we consider alternate branch for docs though, these are the pros and cons:
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.
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.