[REQUEST] Provide API docs with plain doxygen styling

[w0utert]

Is your feature request related to a problem? Please describe.

Previously OpenVDB API docs on openvdb.org used plain Doxygen styling, but nowadays they are styled to look a bit fancier, and integrate the API documentation parts with rest of the documentation in the table of contents sidebar.

As someone who regularly needs to look up OpenVDB/NanoVDB API's I have found the new styling to be a significant regression, class/namespace overviews are now chopped up alphabetically, it is cumbersome to switch between different views, expanding them will only use the narrow side-bar and push other side-bar content off the screen, no summaries of API functions in the namespace/class index, etc.

I often don't know exactly what I'm looking for or what it is called, and previously I would just scan a namespace to find potential candidates for what I need, this doesn't work anymore with the new styling.

IMO the default doxygen styling has much better usability and also has the advantage of familiarity (many other projects use it). I really couldn't care less about the aesthetics of API documentation so it would be nice if there would at least be the option to switch to the classic Doxygen style.

Describe the solution you'd like

A link on the documentation landing page and/or from the index to open the API docs with classic Doxygen styling

Describe alternatives you've considered

I can build the doxygen documentation locally and open it from there, but I would much prefer to use the official up-to-date documentation hosted on openvdb.org

[Idclip]

I don't think we'd host multiple versions with different styling, it would never end. But we can obviously fix any issues with the current styling and revert where it makes sense to do so.

Would you mind providing a few comparison images showing what you prefer from the old styling in regards to these comments:

• expanding them will only use the narrow side-bar and push other side-bar content off the screen
• I would just scan a namespace to find potential candidates for what I need, this doesn't work anymore with the new styling.

With regards to:

• class/namespace overviews are now chopped up alphabetically
• no summaries of API functions in the namespace/class index

My understanding is that these should not have changed. Can you provide me a old/new screenshot showing what you're referring to?

With regards to:

has the advantage of familiarity (many other projects use it)

Would you mind linking some other projects of styling you like. It will help with understanding your comments.

You should also be able to go back to the old styling simply by commenting out doxygen-awesome usage in the doc's cmake, should you wish to compare the docs 1:1 on master:

[w0utert]

Most of the usability regression is coming from the fact that the new style does not have the top nav/tab bar anymore, and navigation is all crammed into the left table-of-contents bar which expands its contents and moves all navigation off the screen to 'somewhere above or below this' that you have to scroll to. Another regression is that in some places sections are now by default collapsed where they should be expanded, or expanded where they should be collapsed. And some things like class/function descriptions are now not visible anymore in the top-level views because the left-side panel is used more as an index instead of a section listing.

Let's take the old OpenVDB documentation which uses the 'classic' Doxygen layout (except in a red theme instead of the default blue, but that's fine).

Class index: old one is unfolded by default and has class descriptions, new one only unfolds the top level and has no class descriptions. Need to expand/collapse the sections to see them.

Left-hand index panel pushes everything off the screen if you expand a section, and now I need to scroll to 'somewhere above' or 'somewhere below' to for example switch from class to namespace view

In the old style there was always this navbar, always at the top, so switching between namespaces/files/classes was just a matter of pressing HOME and using the navbar.

The navbar also has the breadcrumbs to simplify up/down navigation which is completely absent in the new style

Namespace listing/folding is also not clear in the new style, for example in the following screenshot there is no visual indication whatsoever that the namespaces have child namespaces and what they are named:

Only when you hover them and click them you can expand them and see what more is there:

Compare this to the old namespace list which was by default expanded and provided a complete overview at a single glance:

These are just a few things that come to mind, there are more papercuts here and there I cannot quickly create examples of, but all in all I've found that since you switched to this style (which I think was around OpenVDB 11) every time I need to use the documentation I struggle to find things.

I will immediately believe that there are usability workarounds to adapt to the new style and make it work, but my point about the default style (what OpenVDB was originally using) was that this should probably not be necessary.

Off the top of my head, some examples of a few projects I use that use the default layout (some do have a bit of added styling, but mostly aesthetic):

• All Apache projects, for example Mesos (https://mesos.apache.org/api/latest/c++/namespacemesos.html)
• Box2D (https://louis-langholtz.github.io/Box2D/API/annotated.html)
• VTK (https://vtk.org/doc/nightly/html/annotated.html)
• Open CASCADE (https://occt3d.com/dev/doc/refman/html/namespaces.html)

There's also many that do style their Doxygen API docs very heavily, or don't use doxygen at all but something else, but they never annoy me enough to take the time to file a feature request ticket with them :-P

• CGAL (https://doc.cgal.org/latest/Manual/general_intro.html)

[Idclip]

Thanks a lot for the details @w0utert - for context, one of the main reasons we switched to the new styling was that we're, unfortunately, using doxygen for both actual documentation as well as source code documentation generation (we really need two systems). It improved the prior significantly and I did not experience the pain points you're highlighting. But I appreciate your feedback, doing away with the side bar/bringing back the top level navigation is very easy to do - but let me take a deeper look at the examples you've provided and get back to you (we have a major release at the end of October so I'll endeavour to have a response for then).