Brief lists of MLL functions in each section

[smguzik]

Is there an automatic way to recover the dense summaries of functions in each section, like we had in the old documentation. Something like a function name or signature and doxygen brief?

I find the new docs too verbose and spread out to easily use as a reference.

[MicK7]

Something like this may help in listing functions but not sure that it create links

.. doxygengroup:: AccessingANode
    :content-only:
    :outline:

The hdf5 current documentation has a listing at the top with linking to detailed functions documentation. I haven't figured out how they did it yet.

I am not sure that adding a brief list is very necessary. We do not have a big list of function for each section so the presentation is going to look a bit bloated.

[smguzik]

I think it helps as often we have 3 or more ways to do something - you can find the function you want more easily. Using the breathe outline, the full signature is too wordy. Would prefer something like below (just a portion is shown). I don't think its a big deal to manually write the functions. It would be nice to pull the brief from doxygen but I think we'd have to write an extension to do so. I made a branch for testing this.

[brtnfld]

I favor it as long as we don't have to maintain the summary manually. You can probably do it in Doxygen with JAVADOC_AUTOBRIEF and AUTOBRIEF_FORMAT, or you might need to do two breathe runs, one with show-brief-only = False and one with true. Then, use the true output for the summary section. I'm not sure, though.

[brtnfld]

There seems to be an error when generating the HTML in the action:

https://github.com/CGNS/cgns.github.io/actions/runs/12762105201/job/35570118301

It runs on my OpenSUSE box, which has Sphinx and Python versions 8.1.3 and 3.12. Is the Sphinx version problematic?

[MicK7]

There seems to be an error when generating the HTML in the action:

https://github.com/CGNS/cgns.github.io/actions/runs/12762105201/job/35570118301

It runs on my OpenSUSE box, which has Sphinx and Python versions 8.1.3 and 3.12. Is the Sphinx version problematic?

It is the python version that is problematic. The provided code by Stephen requires at least a python 3.9 version to handle the typing hints.

[smguzik]

Upgrading python seems like the best fix. There is also the option to remove the typing hints.

[brtnfld]

The website is now updated.

For some reason, the toggle primary sidebar pops out instead of hiding it now. Strange.

[smguzik]

Something is weird in the contents list. For example, if I click on Grid Specification, it shows it in the main pane, but expands Auxiliary Data in the contents list. I don't see that behavior offline (but when I compile offline, I seem to be using a different theme. Are you seeing the same theme online and offline?).

The summaries also have excessive underlining. Is that intended?

[brtnfld]

I see the same theme off and online. It is much better rendered using the Firefox engine; it does not have the issue with Auxiliary data expansion. I don't see excessive underlining, but if there is no reason for the underlining, then it is not intended.

Would using a newer version of the theme help? At least for OpenSUSE, it uses v0.2; the latest release is v1.1.3.

I created issue #19 .