Update the style of Doxygen generated API Documentation

[louis-langholtz]

Expected/Desired Behavior or Experience:

The style of the API documentation is consistent with the markdown/web style at the IO web pages.

Actual Behavior:

The style of the API documentation is basically the default Doxygen HTML output style.

Steps to Reproduce the Actual Behavior:

To see the difference in style in a side-by-side manner, open one browser window to IO web pages, and open another browser window to API documentation at the same time and compare the styles.

[louis-langholtz]

Seems Doxygen doesn't generate Markdown as any of its output formats. So the suggested path towards this is to use Doxygen to output XML and then to use an XML to markdown converter tool.

Some XML to markdown converter tools (in order of preference/maturity first being highest):

1. Pandoc.
2. Moxygen.
3. doxygen2md.

[louis-langholtz]

Another reference source I want to look into: http://docs.wxwidgets.org/3.0/index.html

I'm impressed with how their doxygen output looks cleaner than usual.

[ivorne]

Hi, I spent a few hours trying to solve this and I think I got a pretty good result. Changes are in commit ded4480 in my repo. Resulting documentation is here: https://ivorne.github.io/PlayRho/ .

I also made a Github Action .github/workflows/documentation.yml that builds and deploys documentation to gh-pages each time a commit is pushed to the repo. The deploy part of the script will need to be modified to deploy to the correct directory of your gh-pages repo.

It works using Bootstrap js library. Because the part that applies the theme depends on structure of the generated html, Doxygen >= 1.8.17 is required. It may also break with future Doxygen versions, but it's not overly fragile.

Most dirty work is done in repository https://github.com/ivorne/doxyboot-cmake that was added as a new git submodule.

I also use that submodule in my project, and the whole approach is taken from https://github.com/Velron/doxygen-bootstrapped (Biogears), so there is a similarity between those documentations (the design is not fully original for PlayRho), but its not too bad, I'd say.

[louis-langholtz]

Thanks so much for spending time on this!!

I'm still looking at the documentation generated and what this solution entails. Saw lots of things that I liked better than the current API!

A couple things I found so far that I'm liking less are:

1. The examples don't seem to have the file contents listed anymore. Take the Body.cpp example for instance in this new way vs. the current way.
2. Adding another git submodule to get this done.

As for Github Actions, that seems like a feature of Github that got added like within the last 3 years. Is that correct? Admittedly, I haven't been keeping up with Github developments like that.

How do Github actions differ from the commit hook like actions which this project has been activating on pull requests and pushes (where AppVeyor CI and Travis CI are run)? For instance, the AppVeyor CI's architectural independent job has been automatically running Doxygen to test and generate API pages. I don't think I got those results hooked into automatically deploying to gh-pages though.

Seems like getting the API pages automatically generated and deployed to github.io could be a separate pull-request. That'd be preferable to me if that's possible but I haven't gotten far enough with understanding where Github actions fits in with the existing action like things I have this project setup to do already.

Thanks again!

[ivorne]

1. Missing examples - Alright, I fixed that. It was missing EXAMPLE_PATH in Doxyfile.

2. Git submodule - It is not that many files, so they can be copied straight to the repository, removing the submodule. On the other hand, I have some improvements planned (for example moving detailed class description on top of the class doc file) and maybe when something breaks in the future, I might fix it. It will be easier to integrate those changes. But I shouldn't care, it's your project.

3. Github Actions - As I understand it, it's similar to Travis CI, so this same behavior should be possible with Travis CI. Yes, I heard that its quite new, but I am not sure about the details, I never used any CI before, I just started with it and I chose Github Actions. I know how to implement this behavior in Actions, I don't know how to do it with Travis. I can make it a separate PR. I won't learn Travis though. Again, you decide.

Thanks for the interest in my contribution!

[louis-langholtz]

Something of a side note...

From my recent experience with doxygen issue #8017, I'm inclined to see more development of the Clang-Doc tool as maybe originally described by Gribenko. While Doxygen may have been best in its class, having a full fledged C++ parser behind deriving documentation seems like it would be even better. Not sure if the Clang folks intend to replace Doxygen or to retool Doxygen to use its AST capabilities. Either way, I'm really interested in seeing where that goes and keeping it in mind for this issue as well.

[louis-langholtz]

Overall, I prefer the way your new docs look. Does it loose any info or does the info just appear less concise though? Not sure. I don't want to hold up release 1.0 though for this so changing milestone to 1.0+.

[ivorne]

The contents should be the same as in the original Doxygen documentation. The only intended changes are in appearance.

The way it works is that docs are generated using doxygen_add_docs CMake command, then an extra CSS file is added (https://github.com/ivorne/doxyboot-cmake/blob/master/theme/customdoxygen.css), HTML is restructured using custom Bootstrap rules (https://github.com/ivorne/doxyboot-cmake/blob/master/theme/doxy-boot.js) and custom HTML header and footer is used.