Incorporate Doxygen docs into the new website.

[brtnfld]

Using Doxygen+Breathe+Sphinx, generate the MLL and other API documentation and include it in the website.

[brtnfld]

@MicK7, I've completed the C MLL Doxygen into Read-the-docs. I created a docs directory in the CGNS repo and processed it in-place: https://github.com/brtnfld/CGNS/tree/breathe. If interested, you can build it by doing "make html" in the docs directory. You can view the results from _build/html/index/html

I'm wondering if we should add the CGNS source as a submodule in this repo and process it as part of an action or generate the webpage in the CGNS repository and reference it from this repo. What are your thoughts on the best way to do this?

It would be nice to version the documentation generated with a released version of CGNS.

Getting the C MLL into the website as proof of concept would be good before proceeding to the other documentation.

[brtnfld]

• move the CGNS-Rest-site contents to the top-level directory
• remove references to cgnstalk mailing list
• Remove install information and point to install information on GitHub instead to avoid this information in two places.

[MicK7]

@brtnfld I tried to move the content to the top-level directory but I am not sure it does not look messy for a contributor as the "CGNS" library directory is now mixed in the middle. Maybe it should be noted somewhere (README.md or other) that this directory is special.

[MicK7]

I think we should now rename the transition branch to be the master branch.

[brtnfld]

I like the model in which we have a "develop" branch and a master branch where the material "goes live" on the web and can be tagged for releases.

We can rename the CGNS source directory to something else less confusing.

[MicK7]

I have switched the default branch to master. We can add a develop whenever we want.
I also renamed the modern and previous repository to test if the new documentation site will display properly at a new location.

[MicK7]

I just noticed that the "Family Hierarchy Tree" section (https://cgns.github.io/cgns-archives/CGNS_docs_current/midlevel/families.html) is missing in the doxygen site.

edit: Now added

[smguzik]

Nice work. I noticed some of the documentation, e.g., the guidance for discrete nodes, is missing in the new docs. Is this placed somewhere else? Otherwise, what is the plan for not losing such info? Is it just a manner of moving it into comment blocks in the code and needed hands on keyboard? I'm writing some CGNS code now and can help if needed.

[MicK7]

Nice work. I noticed some of the documentation, e.g., the guidance for discrete nodes, is missing in the new docs. Is this placed somewhere else? Otherwise, what is the plan for not losing such info? Is it just a manner of moving it into comment blocks in the code and needed hands on keyboard? I'm writing some CGNS code now and can help if needed.

Thanks for reporting the issue. It should be there; https://cgns.github.io/standard/MLL/api/c_api.html#discrete-data

As for the plan, reporting issues here so that information losses can be tracked is the preferred way.
And, yes, it is mainly a manner of moving it into comment blocks in the code.

[brtnfld]

• Address broken links reported: https://github.com/CGNS/cgns.github.io/actions/runs/12476927798/job/34822415275#step:7:3017

[smguzik]

The function descriptions for the discrete nodes are there. The following text with a bit of guidance on how to use them is missing. Where do we put this?

DiscreteData_t nodes are intended for the storage of fields of data not usually identified as part of the flow solution, such as fluxes or equation residuals.

The description for these functions is similar to the FlowSolution_t node as described above. To read and write the discrete data, use cg_goto to access the DiscreteData_t node, then cg_array_read and cg_array_write. The dimensions provided to the array-write family of functions must match the dimensions specified by the Zone_t and DiscreteData_t nodes. Use cg_gridlocation_write and cg_rind_write under the DiscreteData_t node, as required.

[brtnfld]

If it is a general statement (i.e., not tied to a specific API), you can add it here: https://github.com/CGNS/cgns.github.io/blob/master/source/standard/MLL/api/c_api.rst

in the correct section.

To reference APIs, you need to add in the document, for example:

.. cpp:function:: cg_goto() 

This refers to the :cpp:function:`cg_goto()` function.

I've not tried this, so I'm not 100% sure this will work. But this is what Gemini says to do, so maybe it will work 😏

[smguzik]

@brtnfld @MicK7 I made a branch with a trial commit of adding guidance back in for the Discrete Data functions.

What is the vision for achieving this? Should this be reformatted in rst or is it okay to just copy over the html from the archives? For the latter, I still had to update the links to point within the same file which is probably fine. Not sure if there is a straightforward and reliable way to link to something like a function.

[MicK7]

@brtnfld @MicK7 I made a branch with a trial commit of adding guidance back in for the Discrete Data functions.

What is the vision for achieving this? Should this be reformatted in rst or is it okay to just copy over the html from the archives? For the latter, I still had to update the links to point within the same file which is probably fine. Not sure if there is a straightforward and reliable way to link to something like a function.

Hi @smguzik I reformatted in rst your change. It should correctly link to the function. I haven't tested it yet.

[smguzik]

@MicK7 That works even better with links now going directly to the functions.

This is just one of many missing pieces of documentation. I'll work on adding the others in this branch using rst format.