From be364584643deb7347b8d06303e08a613574baa9 Mon Sep 17 00:00:00 2001 From: Stephen Guzik Date: Mon, 13 Jan 2025 21:20:35 -0500 Subject: [PATCH] Mll section summaries (#16) Added summaries of functions in each section. Added extension that automatically makes summaries of functions in a section. Created summaries of MLL and parallel sections using this custom directive. Tested on sphinx 5.3.0. All summaries are automatically produced from doxygen with the exception of the Configuring CGNS Internals section which is written manually. Additional fixes: 1) Added missing flow solution data functions to MLL documentation. 2) Made references consistent with doxygen xml sources where different (in most cases these were consistent). 3) Slightly restructured parallel api rst doc primarily to better position references. --- _ext/cgns_function_summary.py | 221 +++++++++++++++++++++ conf.py | 5 +- source/standard/MLL/api/c_api.rst | 122 +++++++++++- source/standard/MLL/api/c_parallel_api.rst | 82 +++++--- 4 files changed, 391 insertions(+), 39 deletions(-) create mode 100644 _ext/cgns_function_summary.py diff --git a/_ext/cgns_function_summary.py b/_ext/cgns_function_summary.py new file mode 100644 index 00000000..85aee27c --- /dev/null +++ b/_ext/cgns_function_summary.py @@ -0,0 +1,221 @@ +from docutils import nodes +from sphinx.util.docutils import SphinxDirective +from sphinx.addnodes import pending_xref +from pathlib import Path +import re + +class CGNSExtractDoxygenFunctionsDirective(SphinxDirective): + """ + A Sphinx directive to extract function names and their brief descriptions + from Doxygen-generated XML files. The extracted information is displayed as + a nested bullet list in the documentation. + + Arguments: + group_name (str): The name of the group, used to locate the + corresponding Doxygen XML file. This is the first required argument. + The group_name is the same as used for the doxygengroup directive. + The XML file is expected to be at xml/group__{group_name} where + any underscores in group_name are repeated (so they appear twice). + A link is expected elsewhere in the rst file with the format + .. _{group_name}-ref: + group_name_display_text (str, optional): A custom display text for the + group name in the generated documentation. If not provided, a + formatted version of `group_name` is used. + + Usage: + .. cgns-group-function-summary:: DataArrays + + The group name is formatted as Data Arrays. The xml file is + xml/group__DataArrays.xml. + + .. cgns-group-function-summary:: CGNSFile Opening and Closing a CGNS File + + The group name is Opening and Closing a CGNS File. The xml file is + xml/group__CGNSFile.xml. + """ + required_arguments = 1 # Argument for group name + optional_arguments = 1 + final_argument_whitespace = True + option_spec = {} + + def run(self): + # Get the group name from the directive argument + group_name = self.arguments[0] + xml_file = f"group__{group_name.replace('_', '__')}.xml" + full_path = Path(self.env.app.confdir) / 'xml' / xml_file + + # Check if the XML file exists + if not full_path.exists(): + error = self.state_machine.reporter.error( + f"File not found: {xml_file}", + nodes.literal_block(self.block_text, self.block_text), + line=self.lineno, + ) + return [error] + + # Extract function names and descriptions + functions = self._extract_functions(full_path) + + # Create a bullet list node for the group + bullet_list = nodes.bullet_list() + + # Create the main list item for the group name + group_item = nodes.list_item() + group_paragraph = nodes.paragraph() + + # Add the group name as a reference + group_ref = pending_xref('', refdomain='std', reftype='ref', + reftarget=f"{group_name.lower()}-ref", + refexplicit=True) + # Format the group name for display by adding a space before each + # capital letter after the first. + group_name_display_text = ( + self.arguments[1] if len(self.arguments) > 1 else ''.join( + [' ' + char if char.isupper() and i > 0 else char + for i, char in enumerate(group_name)])) + group_ref += nodes.Text(group_name_display_text) + group_paragraph += group_ref + group_item += group_paragraph + + # Create a sublist for the functions + sublist = nodes.bullet_list() + + for func_name, func_desc in functions: + # Create a list item for each function + func_item = nodes.list_item() + func_paragraph = nodes.paragraph() + + # Create a cross-reference node for :cpp:func: + xref = pending_xref('', refdomain='cpp', reftype='func', + reftarget=func_name, refexplicit=True) + xref += nodes.literal('', func_name) + func_paragraph += xref + if func_desc: + func_paragraph += nodes.Text(f" - {func_desc}") + else: + func_paragraph += nodes.Text( + " - ⚠️ No description provided.") + func_item += func_paragraph + sublist += func_item + + # Add the sublist to the group item + group_item += sublist + bullet_list += group_item + + return [bullet_list] + + def _extract_functions(self, file_path: Path) -> list[tuple[str, str]]: + """ + Scan the XML file and extract function names and descriptions. + Only considers and tags within a + block. + """ + functions = [] + with file_path.open("r") as file: + func_name = None + func_desc = None + inside_brief = False + inside_func = False + buffer = [] # Buffer for handling multi-line content + + for line in file: + # Detect start of + if ' + if '' in line: + inside_func = False + + # Look for function name + elif "" in line: + # Name found without brief description + if func_name is not None: + functions.append((func_name, "")) + # Issue warning if inside brief + if inside_brief: + self.state_machine.reporter.warning( + "Invalid XML structure: tag found " + "inside . This indicates a " + "malformed XML file. Previous description " + "discarded.", + line=self.lineno) + inside_brief = False + func_name = self._extract_tag_content(line, "name") + + # Detect start of + elif "" in line: + if inside_brief: + self.state_machine.reporter.warning( + "Invalid XML structure: found nested " + ". This indicates a " + "malformed XML file.", + line=self.lineno) + if func_name is None: + self.state_machine.reporter.warning( + "Invalid XML structure: found " + " without function name. " + "This indicates a malformed XML file.", + line=self.lineno) + inside_brief = True + buffer = [] + + # Detect end of + elif "" in line: + if not inside_brief: + self.state_machine.reporter.warning( + "Invalid XML structure: found " + " before " + ". This indicates a " + "malformed XML file.", + line=self.lineno) + elif func_name is None: + self.state_machine.reporter.warning( + "Invalid XML structure: found " + " without function name. " + "This indicates a malformed XML file.", + line=self.lineno) + else: + # Extract the brief description from buffered + # content + func_desc = self._extract_tag_content( + "".join(buffer), "para") + functions.append((func_name, func_desc or "")) + inside_brief = False + func_name = None + func_desc = None + + # Collect lines inside + elif inside_brief: + buffer.append(line) + + # If we ended with a name and no description, save the name + if func_name is not None: + functions.append((func_name, "")) + + return functions + + def _extract_tag_content(self, text: str, tag: str) -> str: + """ + Extract content between and , handling multi-line tags. + Removes any nested tags found within the extracted content. + """ + start = text.find(f"<{tag}>") + end = text.find(f"") + if start != -1 and end != -1: + content = text[start + len(f"<{tag}>") : end].strip() + # Remove any nested tags + content = re.sub(r"<[^>]+>", "", content) + return content + return "" + +def setup(app): + app.add_directive("cgns-group-function-summary", + CGNSExtractDoxygenFunctionsDirective) + return { + "version": "1.0", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/conf.py b/conf.py index 9015edfa..ea34e00c 100644 --- a/conf.py +++ b/conf.py @@ -14,7 +14,9 @@ # sys.path.insert(0, os.path.abspath('.')) from sphinx.builders.html import StandaloneHTMLBuilder import subprocess, os, sys +from pathlib import Path sys.path.insert(0, os.path.abspath('.')) +sys.path.append(str(Path('_ext').resolve())) # Doxygen subprocess.call('doxygen Doxyfile', shell=True) @@ -47,7 +49,8 @@ 'sphinx.ext.inheritance_diagram', 'sphinxfortran.fortran_domain', 'sphinxfortran.fortran_autodoc', - 'breathe' + 'breathe', + 'cgns_function_summary' ] # Prefix to add to ticket numbers to get the full URL to JIRA # see use in the News page diff --git a/source/standard/MLL/api/c_api.rst b/source/standard/MLL/api/c_api.rst index 7155b1ba..0e42a206 100644 --- a/source/standard/MLL/api/c_api.rst +++ b/source/standard/MLL/api/c_api.rst @@ -10,12 +10,35 @@ These are all the types and functions available in the CGNS C API. Please refer to :ref:`MLLGeneralRemarks-ref` for details and conventions regarding the equivalent Fortran APIs, paying special attention to :ref:`CGNSFortranPort-ref`. -.. _CGNSFile-ref: - ****************************************** File and Library Operations ****************************************** +.. cgns-group-function-summary:: CGNSFile Opening and Closing a CGNS File + +.. + Because of the way internals is split into two groups, this summary of functions is done manually. CGNSInternals_FNC_CG_CONFIG has no matching reference. The manual implementation merges the output of the following: +.. + cgns-group-function-summary:: CGNSInternals_FNC_CG_CONFIG Configuring CGNS Internals +.. + cgns-group-function-summary:: CGNSInternals Configuring CGNS Internals + +* :ref:`Configuring CGNS Internals` + + * :cpp:func:`cg_configure` - Configure CGNS library internal options. + * :cpp:func:`cg_error_handler` - Set CGNS error handler + * :cpp:func:`cg_set_compress` - Set CGNS compression mode. + * :cpp:func:`cg_get_compress` - Get CGNS compression mode. + * :cpp:func:`cg_set_path` - Set the CGNS link search path. + * :cpp:func:`cg_add_path` - Add to the CGNS link search path. + +.. cgns-group-function-summary:: CGNSInterfaceCGIO Interfacing with CGIO + +.. _CGNSFile-ref: + +CGNS File Operations +____________________________________________ + .. doxygengroup:: CGNSFile :content-only: @@ -48,6 +71,9 @@ ____________________________________________ Navigating a CGNS File ********************** +.. cgns-group-function-summary:: AccessingANode +.. cgns-group-function-summary:: DeletingANode + .. _AccessingANode-ref: Accessing a Node @@ -75,6 +101,8 @@ ____________________________________________ Error Handling ********************** +.. cgns-group-function-summary:: ErrorHandling + .. doxygengroup:: ErrorHandling :content-only: @@ -84,6 +112,10 @@ Error Handling Structural Nodes ********************** +.. cgns-group-function-summary:: CGNSBaseInformation CGNS Base Information +.. cgns-group-function-summary:: CGNSZoneInformation CGNS Zone Information +.. cgns-group-function-summary:: SimulationType + .. _CGNSBaseInformation-ref: CGNS Base Information @@ -134,6 +166,9 @@ ____________________________________________ Descriptors ********************** +.. cgns-group-function-summary:: DescriptiveText +.. cgns-group-function-summary:: OrdinalValue + .. _DescriptiveText-ref: Descriptive Text @@ -166,6 +201,12 @@ ____________________________________________ Physical Data ********************** +.. cgns-group-function-summary:: DataArrays +.. cgns-group-function-summary:: DataClass +.. cgns-group-function-summary:: DataConversionFactors +.. cgns-group-function-summary:: DimensionalUnits +.. cgns-group-function-summary:: DimensionalExponents + .. _DataArrays-ref: Data Arrays @@ -182,7 +223,7 @@ ____________________________________________ .. _DataClass-ref: -Data Class (DataClass_t) +Data Class ____________________________________________ .. raw:: html @@ -240,6 +281,10 @@ _________________________________________________________________ Location and Position ********************** +.. cgns-group-function-summary:: GridLocation +.. cgns-group-function-summary:: PointSets +.. cgns-group-function-summary:: RindLayers + .. _GridLocation-ref: Grid Location @@ -293,6 +338,13 @@ ____________________________________________ Auxiliary Data ********************** +.. cgns-group-function-summary:: ReferenceState +.. cgns-group-function-summary:: Gravity +.. cgns-group-function-summary:: ConvergenceHistory +.. cgns-group-function-summary:: IntegralData +.. cgns-group-function-summary:: UserDefinedData +.. cgns-group-function-summary:: FreeingMemory + .. _ReferenceState-ref: Reference State @@ -377,6 +429,11 @@ ____________________________________________ Grid Specification ********************** +.. cgns-group-function-summary:: ZoneGridCoordinates +.. cgns-group-function-summary:: ElementConnectivity +.. cgns-group-function-summary:: Axisymmetry +.. cgns-group-function-summary:: RotatingCoordinates + .. _ZoneGridCoordinates-ref: Zone Grid Coordinates @@ -421,7 +478,7 @@ ____________________________________________ ------ -.. _Rotating-ref: +.. _RotatingCoordinates-ref: Rotating Coordinates ____________________________________________ @@ -439,6 +496,11 @@ ____________________________________________ Solution Data ********************** +.. cgns-group-function-summary:: FlowSolution +.. cgns-group-function-summary:: FlowSolutionData +.. cgns-group-function-summary:: DiscreteData +.. cgns-group-function-summary:: ZoneSubregions + .. _FlowSolution-ref: Flow Solution @@ -453,6 +515,16 @@ ____________________________________________ ------ +.. _FlowSolutionData-ref: + +Flow Solution Data +____________________________________________ + +.. doxygengroup:: FlowSolutionData + :content-only: + +------ + .. _DiscreteData-ref: Discrete Data @@ -485,6 +557,11 @@ ____________________________________________ Grid Connectivity ********************** +.. cgns-group-function-summary:: OneToOneConnectivity One-to-One Connectivity +.. cgns-group-function-summary:: GeneralizedConnectivity +.. cgns-group-function-summary:: SpecialGridConnectivityProperty +.. cgns-group-function-summary:: OversetHoles + .. _OneToOneConnectivity-ref: One-to-One Connectivity @@ -545,6 +622,11 @@ ____________________________________________ Boundary Conditions ********************** +.. cgns-group-function-summary:: BoundaryConditionType Boundary Condition Type and Location +.. cgns-group-function-summary:: BoundaryConditionDatasets +.. cgns-group-function-summary:: BCData Boundary Condition Data +.. cgns-group-function-summary:: SpecialBoundaryConditionProperty Special Boundary Condition Properties + .. _BoundaryConditionType-ref: Boundary Condition Type and Location @@ -605,6 +687,13 @@ _________________________________________________________________ Equation Specification ********************** +.. cgns-group-function-summary:: FlowEquationSet +.. cgns-group-function-summary:: ParticleEquationSet +.. cgns-group-function-summary:: GoverningEquations +.. cgns-group-function-summary:: ParticleGoverningEquations +.. cgns-group-function-summary:: AuxiliaryModel +.. cgns-group-function-summary:: ParticleModel + .. _FlowEquationSet-ref: Flow Equation Set @@ -692,6 +781,12 @@ ________________________________________________ Families ********************** +.. cgns-group-function-summary:: CGNSFamilyDefinition Family Definition +.. cgns-group-function-summary:: CGNSFamilyHierarchyTreeDefinition Family Hierarchy Tree +.. cgns-group-function-summary:: CGNSGeometryReference Geometry Reference +.. cgns-group-function-summary:: CGNSFamilyBoundaryCondition Family Boundary Condition +.. cgns-group-function-summary:: FamilyName + .. _CGNSFamilyDefinition-ref: Family Definition @@ -720,7 +815,7 @@ ____________________________________________ ------ -.. _CGNSGeometry-ref: +.. _CGNSGeometryReference-ref: Geometry Reference ____________________________________________ @@ -766,6 +861,13 @@ ____________________________________________ Time-Dependent Data ********************** +.. cgns-group-function-summary:: BaseIterativeData +.. cgns-group-function-summary:: ZoneIterativeData +.. cgns-group-function-summary:: ParticleIterativeData +.. cgns-group-function-summary:: RigidGridMotion +.. cgns-group-function-summary:: ArbitraryGridMotion +.. cgns-group-function-summary:: ZoneGridConnectivity + .. _BaseIterativeData-ref: Base Iterative Data @@ -867,6 +969,8 @@ ________________________________________________ Links ********************** +.. cgns-group-function-summary:: Links + .. _Links-ref: .. doxygengroup:: Links @@ -877,6 +981,11 @@ Links Particle Specification ********************** +.. cgns-group-function-summary:: ParticleZoneInformation +.. cgns-group-function-summary:: ParticleCoordinates +.. cgns-group-function-summary:: ParticleSolution +.. cgns-group-function-summary:: ParticleSolutionData + .. _ParticleZoneInformation-ref: @@ -921,6 +1030,3 @@ ________________________________________________ .. doxygengroup:: ParticleSolutionData :content-only: - - - diff --git a/source/standard/MLL/api/c_parallel_api.rst b/source/standard/MLL/api/c_parallel_api.rst index ea0b03f1..f90cab40 100644 --- a/source/standard/MLL/api/c_parallel_api.rst +++ b/source/standard/MLL/api/c_parallel_api.rst @@ -15,89 +15,111 @@ the associated routines. It utilizes MPI-IO through the HDF5 library to support parallel I/O operations. As a result, the CGNS library must be built with HDF5 to enable the parallel CGNS APIs. -****************************** -Parallel File Operations -****************************** +.. cgns-group-function-summary:: ParallelFile File Operations +.. cgns-group-function-summary:: ParallelGridCoordinate Grid Coordinate Data +.. cgns-group-function-summary:: ParallelParticleCoordinate Particle Coordinate Data +.. cgns-group-function-summary:: ElementConnectivityData +.. cgns-group-function-summary:: SolutionData Flow Solution Data +.. cgns-group-function-summary:: ParallelParticleSolutionData Particle Solution Data +.. cgns-group-function-summary:: ArrayData +.. cgns-group-function-summary:: ParallelMisc Miscellaneous Routines +.. cgns-group-function-summary:: PointListData PointList Data + .. _ParallelFile-ref: +************************ +Parallel File Operations +************************ + .. doxygengroup:: ParallelFile :content-only: -****************************** -Parallel Grid Coordinate Data -****************************** .. _ParallelGridCoordinate-ref: +***************************** +Parallel Grid Coordinate Data +***************************** + .. doxygengroup:: ParallelGridCoordinate :content-only: -********************************* -Parallel Particle Coordinate Data -********************************* .. _ParallelParticleCoordinate-ref: -Parallel Particle Coordinates -________________________________________________ +********************************* +Parallel Particle Coordinate Data +********************************* .. doxygengroup:: ParallelParticleCoordinate :content-only: ------- - -********************************************* -Parallel Element Connectivity Data -********************************************* .. _ElementConnectivityData-ref: +********************************** +Parallel Element Connectivity Data +********************************** + .. doxygengroup:: ElementConnectivityData :content-only: -****************************** + +.. _SolutionData-ref: + +*************************** Parallel Flow Solution Data -****************************** +*************************** .. note:: The application is responsible for ensuring that the data type for the solution data matches that defined in the file; no conversions are done. -.. _SolutionData-ref: - .. doxygengroup:: SolutionData :content-only: + .. _ParallelParticleSolutionData-ref: +******************************* Parallel Particle Solution Data -________________________________________________ +******************************* + +.. note:: + The application is responsible for ensuring that the data type for the solution + data matches that defined in the file; no conversions are done. .. doxygengroup:: ParallelParticleSolutionData :content-only: ------- - -****************************** -Parallel Array Data -****************************** .. _ArrayData-ref: +******************* +Parallel Array Data +******************* + .. doxygengroup:: ArrayData :content-only: -********************************************* + +******************************* Parallel Miscellaneous Routines -********************************************* +******************************* .. _ParallelMisc-ref: +Miscellaneous Routines +________________________________________________ + .. doxygengroup:: ParallelMisc :content-only: -.. doxygengroup:: PointListData - :content-only: +.. _PointListData-ref: +PointList Data +________________________________________________ +.. doxygengroup:: PointListData + :content-only: