From c225416b8ca7efcc08e13503f96dbc08e3c925f3 Mon Sep 17 00:00:00 2001 From: Ryan Aronson Date: Thu, 26 Sep 2024 06:44:40 +0200 Subject: [PATCH] docs: Move table titles from CompleteXMLSchema.rst to corresponding include file (#3321) * alter SchemaToRSTDocumentation to move headers into table files * rename Element to XML Element * avoid includeding headers in table files when included outside of CompleteXMLSchema.rst --------- Co-authored-by: Randolph R. Settgast --- scripts/SchemaToRSTDocumentation.py | 19 ++- .../events/docs/EventManager.rst | 7 +- .../events/docs/TasksManager.rst | 4 +- .../functions/docs/FunctionManager.rst | 5 +- .../fluidFlow/SourceFluxStatistics.cpp | 2 +- src/coreComponents/schema/schema.xsd | 26 ++-- src/coreComponents/schema/schema.xsd.other | 130 +++++++++--------- 7 files changed, 102 insertions(+), 91 deletions(-) diff --git a/scripts/SchemaToRSTDocumentation.py b/scripts/SchemaToRSTDocumentation.py index 23e7613e422..8a7b1a8cda7 100644 --- a/scripts/SchemaToRSTDocumentation.py +++ b/scripts/SchemaToRSTDocumentation.py @@ -13,7 +13,10 @@ def comment(self, data): self.end(etree.Comment) -def writeTableRST(file_name, values): +def writeTableRST(type_name, file_name, title_prefix, values): + + element_header = '%s: %s' % (title_prefix, type_name) + L = [[len(x) for x in row] for row in values] # np isn't in the docker images for our CI @@ -54,7 +57,9 @@ def writeTableRST(file_name, values): # Build table with open(file_name, 'w') as f: - f.write('\n\n') + f.write('%s\n' % (element_header)) + f.write('=' * len(element_header) + '\n') + f.write('\n') f.write(boundary) f.write(formatted_lines[0]) f.write(boundary) @@ -269,13 +274,10 @@ def main(schema_name='schema.xsd', output_folder='./', xsd='{http://www.w3.org/2 for type_name in sorted(input_attribute_map.keys()): # Write the individual tables table_values = buildTableValues(input_attribute_map[type_name]) - writeTableRST('%s/%s.rst' % (datastructure_folder, type_name), table_values) + writeTableRST( type_name, '%s/%s.rst' % (datastructure_folder, type_name), 'XML Element', table_values) # Write to the master list - element_header = 'Element: %s' % (type_name) output_handle.write('\n.. _XML_%s:\n\n' % (type_name)) - output_handle.write('%s\n' % (element_header)) - output_handle.write('=' * len(element_header) + '\n') output_handle.write('.. include:: %s.rst\n\n' % (type_name)) # Parse the non-input schema definitions @@ -288,13 +290,10 @@ def main(schema_name='schema.xsd', output_folder='./', xsd='{http://www.w3.org/2 table_values = buildTableValues(other_attribute_map[type_name], link_string='DATASTRUCTURE', include_defaults=False) - writeTableRST('%s/%s_other.rst' % (datastructure_folder, type_name), table_values) + writeTableRST( type_name, '%s/%s_other.rst' % (datastructure_folder, type_name), 'Datastructure', table_values) # Write to the master list - element_header = 'Datastructure: %s' % (type_name) output_handle.write('\n.. _DATASTRUCTURE_%s:\n\n' % (type_name)) - output_handle.write('%s\n' % (element_header)) - output_handle.write('=' * len(element_header) + '\n') output_handle.write('.. include:: %s_other.rst\n\n' % (type_name)) diff --git a/src/coreComponents/events/docs/EventManager.rst b/src/coreComponents/events/docs/EventManager.rst index d7fde6dc073..8fe6ace3bb8 100644 --- a/src/coreComponents/events/docs/EventManager.rst +++ b/src/coreComponents/events/docs/EventManager.rst @@ -53,7 +53,7 @@ Event The children of the Event block define the events that may execute during a simulation. These may be of type ``HaltEvent``, ``PeriodicEvent``, or ``SoloEvent``. The exit criteria for the global event loop are defined by the attributes ``maxTime`` and ``maxCycle`` (which by default are set to their max values). If the optional logLevel flag is set, the EventManager will report additional information with regards to timestep requests and event forecasts for its children. .. include:: /docs/sphinx/datastructure/Events.rst - + :start-line: 3 PeriodicEvent ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -68,20 +68,21 @@ By default, a PeriodicEvent will execute throughout the entire simulation. This The timestep request event is typically determined via its target. However, this value can be overridden by setting the ``forceDt`` or ``maxEventDt`` attributes. .. include:: /docs/sphinx/datastructure/PeriodicEvent.rst - + :start-line: 3 SoloEvent ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This type of event will execute once once the event loop reaches a certain cycle (targetCycle) or time (targetTime). Similar to the PeriodicEvent type, this event will modify its timestep requests so that a cycle occurs at the exact time requested (this can be turned off by specifying targetExactTimestep="0"). The forecast calculations follow an similar approach to the PeriodicEvent type. .. include:: /docs/sphinx/datastructure/SoloEvent.rst - + :start-line: 3 HaltEvent ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This event type is designed to track the wall clock. When the time exceeds the value specified via maxRunTime, the event will trigger and set a flag that instructs the main EventManager loop to cleanly exit at the end of the current cycle. The event for cast for this event type is given by: ``forecast = (maxRuntime - (currentTime - startTime)) / realDt`` .. include:: /docs/sphinx/datastructure/HaltEvent.rst + :start-line: 3 diff --git a/src/coreComponents/events/docs/TasksManager.rst b/src/coreComponents/events/docs/TasksManager.rst index 22a026a2e38..49ca88b6dc6 100644 --- a/src/coreComponents/events/docs/TasksManager.rst +++ b/src/coreComponents/events/docs/TasksManager.rst @@ -22,12 +22,14 @@ Task The children of the Tasks block define different Tasks to be triggered by events specified in the :ref:`EventManager` during the execution of the simulation. At present the only supported task is the ``PackCollection`` used to collect time history data for output by a TimeHistory output. .. include:: /docs/sphinx/datastructure/Tasks.rst - + :start-line: 3 + PackCollection *************************** The ``PackCollection`` Task is used to collect time history information from fields. Either the entire field or specified named sets of indices in the field can be collected. .. include:: /docs/sphinx/datastructure/PackCollection.rst + :start-line: 3 Note: The time history information collected via this task is buffered internally until it is output by a linked TimeHistory Output. diff --git a/src/coreComponents/functions/docs/FunctionManager.rst b/src/coreComponents/functions/docs/FunctionManager.rst index 18138683c0e..66c1e34e503 100644 --- a/src/coreComponents/functions/docs/FunctionManager.rst +++ b/src/coreComponents/functions/docs/FunctionManager.rst @@ -65,7 +65,7 @@ A table function uses a set of pre-computed values defined at points on a struct Typically, the axes of the table will represent time and/or spatial dimensions; however, these can be applied to represent phase diagrams, etc. .. include:: /docs/sphinx/datastructure/TableFunction.rst - + :start-line: 3 1D Table ************* @@ -158,6 +158,7 @@ This function leverages the symbolic expression library mathpresso to define and These functions are processed using an x86-64 JIT compiler, so are nearly as efficient as natively compiled C++ expressions. .. include:: /docs/sphinx/datastructure/SymbolicFunction.rst + :start-line: 3 The ``variableNames`` attribute defines a set of single-character names for the inputs to the symbolic function. There should be a definition for each scalar input and for each component of a vector input. @@ -188,7 +189,7 @@ This function is derived from the symbolic function. However, instead of using the time or object as inputs, it is used to combine the outputs of other functions using a symbolic expression. .. include:: /docs/sphinx/datastructure/CompositeFunction.rst - + :start-line: 3 The ``functionNames`` attribute defines the set of input functions to use (these may be of any type, and may each have any number of inputs). The ``variableNames`` attribute defines a set of single-character names for each function. diff --git a/src/coreComponents/physicsSolvers/fluidFlow/SourceFluxStatistics.cpp b/src/coreComponents/physicsSolvers/fluidFlow/SourceFluxStatistics.cpp index 42ed3028feb..9667e4270f7 100644 --- a/src/coreComponents/physicsSolvers/fluidFlow/SourceFluxStatistics.cpp +++ b/src/coreComponents/physicsSolvers/fluidFlow/SourceFluxStatistics.cpp @@ -31,7 +31,7 @@ SourceFluxStatsAggregator::SourceFluxStatsAggregator( const string & name, Group * const parent ): Base( name, parent ) { - getWrapper< integer >( Group::viewKeyStruct::logLevelString() ). + getWrapperBase( Group::viewKeyStruct::logLevelString() ). appendDescription( GEOS_FMT( "\n- Log Level 1 outputs the sum of all {0}(s) produced rate & mass,\n" "- Log Level 2 details values for each {0},\n" "- Log Level 3 details values for each region.", diff --git a/src/coreComponents/schema/schema.xsd b/src/coreComponents/schema/schema.xsd index 8bcb61ab88b..2930e0f6b9e 100644 --- a/src/coreComponents/schema/schema.xsd +++ b/src/coreComponents/schema/schema.xsd @@ -1770,6 +1770,10 @@ stress - traction is applied to the faces as specified by the inner product of i + + + + @@ -1822,6 +1826,8 @@ stress - traction is applied to the faces as specified by the inner product of i + + +* Require - Use line search. If smaller residual than starting resdual is not achieved, cut time-step.--> @@ -1922,10 +1928,12 @@ the relative residual norm satisfies: - + + + @@ -1941,15 +1949,15 @@ the relative residual norm satisfies: - + - + - + - + - + - + @@ -2961,7 +2969,7 @@ Local- Add jump stabilization on interior of macro elements--> - + diff --git a/src/coreComponents/schema/schema.xsd.other b/src/coreComponents/schema/schema.xsd.other index 215191d89f5..d59f6b947e5 100644 --- a/src/coreComponents/schema/schema.xsd.other +++ b/src/coreComponents/schema/schema.xsd.other @@ -471,7 +471,7 @@ - + @@ -553,7 +553,7 @@ - + @@ -590,7 +590,7 @@ - + @@ -641,7 +641,7 @@ - + @@ -682,7 +682,7 @@ - + @@ -715,7 +715,7 @@ - + @@ -726,7 +726,7 @@ - + @@ -739,7 +739,7 @@ - + @@ -752,7 +752,7 @@ - + @@ -768,7 +768,7 @@ - + @@ -802,7 +802,7 @@ - + @@ -865,7 +865,7 @@ - + @@ -896,7 +896,7 @@ - + @@ -909,7 +909,7 @@ - + @@ -922,7 +922,7 @@ - + @@ -935,7 +935,7 @@ - + @@ -948,7 +948,7 @@ - + @@ -963,7 +963,7 @@ - + @@ -974,7 +974,7 @@ - + @@ -987,7 +987,7 @@ - + @@ -998,7 +998,7 @@ - + @@ -1009,7 +1009,7 @@ - + @@ -1022,7 +1022,7 @@ - + @@ -1033,7 +1033,7 @@ - + @@ -1044,7 +1044,7 @@ - + @@ -1057,7 +1057,7 @@ - + @@ -1072,7 +1072,7 @@ - + @@ -1087,7 +1087,7 @@ - + @@ -1100,7 +1100,7 @@ - + @@ -1115,7 +1115,7 @@ - + @@ -1126,7 +1126,7 @@ - + @@ -1139,7 +1139,7 @@ - + @@ -1152,7 +1152,7 @@ - + @@ -1168,7 +1168,7 @@ - + @@ -1183,7 +1183,7 @@ - + @@ -1200,7 +1200,7 @@ - + @@ -1217,7 +1217,7 @@ - + @@ -1232,7 +1232,7 @@ - + @@ -1245,7 +1245,7 @@ - + @@ -1284,7 +1284,7 @@ - + @@ -1313,7 +1313,7 @@ - + @@ -1404,7 +1404,7 @@ - + @@ -2958,7 +2958,7 @@ - + @@ -2986,7 +2986,7 @@ - + @@ -3005,11 +3005,11 @@ - + - + @@ -3019,7 +3019,7 @@ - + @@ -3029,11 +3029,11 @@ - + - + @@ -3043,7 +3043,7 @@ - + @@ -3053,7 +3053,7 @@ - + @@ -3063,7 +3063,7 @@ - + @@ -3087,7 +3087,7 @@ - + @@ -3105,7 +3105,7 @@ - + @@ -3117,7 +3117,7 @@ - + @@ -3129,7 +3129,7 @@ - + @@ -3137,11 +3137,11 @@ - + - + @@ -3164,7 +3164,7 @@ - + @@ -3190,7 +3190,7 @@ - + @@ -3211,7 +3211,7 @@ - + @@ -3241,7 +3241,7 @@ - + @@ -3255,7 +3255,7 @@ - + @@ -3282,7 +3282,7 @@ - + @@ -3319,7 +3319,7 @@ - +