From bbd52422297e45baeafd9ad9c52b64c0e13f9fb4 Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Tue, 23 Mar 2021 09:24:21 -0500 Subject: [PATCH 01/12] feat: add nested documentation option to SphinxWriter --- src/axom/inlet/SphinxWriter.cpp | 84 ++++++++++++++++++++++++++++++++- src/axom/inlet/SphinxWriter.hpp | 2 + 2 files changed, 85 insertions(+), 1 deletion(-) diff --git a/src/axom/inlet/SphinxWriter.cpp b/src/axom/inlet/SphinxWriter.cpp index b7207de793..46c10ec97b 100644 --- a/src/axom/inlet/SphinxWriter.cpp +++ b/src/axom/inlet/SphinxWriter.cpp @@ -127,7 +127,8 @@ void SphinxWriter::documentContainer(const Container& container) void SphinxWriter::finalize() { - writeAllTables(); + // writeAllTables(); + writeNestedTables(); m_outFile.open(m_fileName); m_outFile << m_oss.str(); m_outFile.close(); @@ -213,6 +214,87 @@ void SphinxWriter::writeAllTables() } } +void SphinxWriter::writeNestedTables() +{ + for(const auto& pathName : m_inletContainerPathNames) + { + const auto& currContainer = m_rstTables.at(pathName); + + if(!currContainer.isSelectedElement) + { + writeSubtitle(currContainer.containerName); + } + + if(currContainer.description != "") + { + m_oss << currContainer.description << "\n\n"; + } + + const auto& fields = currContainer.fieldTable; + const auto& functions = currContainer.functionTable; + + if(fields.size() > 1 || functions.size() > 1) + { + m_oss << ".. list-table::\n"; + m_oss << " :widths: 25 50\n"; + m_oss << " :header-rows: 1\n"; + m_oss << " :stub-columns: 1\n\n"; + m_oss << " * - Name\n"; + m_oss << " - Description\n"; + } + + // Writes a name + description to the "table of contents" + // for each Container + auto writeTOCEntry = [this](const std::vector& data) { + // FIXME: Overlapping link names? Need to use the full path or a hash?? + m_oss << fmt::format(" * - `{0}`_\n", data[0]); + m_oss << fmt::format(" - {0}\n", data[1]); + }; + + // FIXME: Would it be useful to alphabetize these?? + + // Need to skip first element (header row), hence no range-based for loop + std::for_each(fields.begin() + 1, fields.end(), writeTOCEntry); + std::for_each(functions.begin() + 1, functions.end(), writeTOCEntry); + + // FIXME: Also want to dump the names of child containers... + + m_oss << "\n\n"; + + // Now, dump the full descriptions + std::for_each( + fields.begin() + 1, + fields.end(), + [this](const std::vector& fieldData) { + // Insert a hyperlink target for the name + m_oss << fmt::format(".. _{0}:\n\n", fieldData[0]); + m_oss << fmt::format("**{0}**\n\n", fieldData[0]); // name + // description - ideally this would be an extended description + m_oss << fieldData[1] << "\n\n"; + + // The default value + if(!fieldData[2].empty()) + { + m_oss << fmt::format(" - Default value: {0}\n", fieldData[2]); + } + + // The valid values + if(!fieldData[3].empty()) + { + m_oss << fmt::format(" - Valid values: {0}\n", fieldData[3]); + } + + // Whether it's required + if(!fieldData[3].empty()) + { + const bool isRequired = fieldData[3] == "|check|"; + m_oss << fmt::format(" - {0}\n", isRequired ? "Required" : "Optional"); + } + m_oss << "\n\n"; + }); + } +} + std::string SphinxWriter::getValueAsString(const axom::sidre::View* view) { axom::sidre::TypeID type = view->getTypeID(); diff --git a/src/axom/inlet/SphinxWriter.hpp b/src/axom/inlet/SphinxWriter.hpp index 25b84b4bbf..4cf3ccb560 100644 --- a/src/axom/inlet/SphinxWriter.hpp +++ b/src/axom/inlet/SphinxWriter.hpp @@ -107,6 +107,8 @@ class SphinxWriter : public Writer */ void writeAllTables(); + void writeNestedTables(); + /*! ******************************************************************************* * \struct ContainerData From d5e16855f6e45aa23fae80ec318a1acd07e0d0c4 Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Tue, 23 Mar 2021 10:01:09 -0500 Subject: [PATCH 02/12] feat: added container documentation to nested Sphinx format --- src/axom/inlet/SphinxWriter.cpp | 32 +++++++++++++++++++++++++++++--- src/axom/inlet/SphinxWriter.hpp | 1 + 2 files changed, 30 insertions(+), 3 deletions(-) diff --git a/src/axom/inlet/SphinxWriter.cpp b/src/axom/inlet/SphinxWriter.cpp index 46c10ec97b..68e0687235 100644 --- a/src/axom/inlet/SphinxWriter.cpp +++ b/src/axom/inlet/SphinxWriter.cpp @@ -123,6 +123,27 @@ void SphinxWriter::documentContainer(const Container& container) { extractFunctionMetadata(function_entry.second->sidreGroup(), currContainer); } + + // If it's not a collection, we need to record the child containers + if(!isCollectionGroup(container.name())) + { + for(const auto& container_entry : container.getChildContainers()) + { + if(!isCollectionGroup(container_entry.first) && + !detail::isTrivial(*container_entry.second)) + { + const auto name = removeBeforeDelimiter(container_entry.first); + std::string description; + if(container_entry.second->sidreGroup()->hasView("description")) + { + description = + container_entry.second->sidreGroup()->getView("description")->getString(); + } + currContainer.childContainers.push_back( + {std::move(name), std::move(description)}); + } + } + } } void SphinxWriter::finalize() @@ -232,8 +253,10 @@ void SphinxWriter::writeNestedTables() const auto& fields = currContainer.fieldTable; const auto& functions = currContainer.functionTable; + const auto& containers = + currContainer.childContainers; // Contains only names and descriptions - if(fields.size() > 1 || functions.size() > 1) + if(fields.size() > 1 || functions.size() > 1 || !containers.empty()) { m_oss << ".. list-table::\n"; m_oss << " :widths: 25 50\n"; @@ -252,13 +275,16 @@ void SphinxWriter::writeNestedTables() }; // FIXME: Would it be useful to alphabetize these?? + for(const auto& container : containers) + { + m_oss << fmt::format(" * - `{0}`_\n", container.first); + m_oss << fmt::format(" - {0}\n", container.second); + } // Need to skip first element (header row), hence no range-based for loop std::for_each(fields.begin() + 1, fields.end(), writeTOCEntry); std::for_each(functions.begin() + 1, functions.end(), writeTOCEntry); - // FIXME: Also want to dump the names of child containers... - m_oss << "\n\n"; // Now, dump the full descriptions diff --git a/src/axom/inlet/SphinxWriter.hpp b/src/axom/inlet/SphinxWriter.hpp index 4cf3ccb560..5a12bc519e 100644 --- a/src/axom/inlet/SphinxWriter.hpp +++ b/src/axom/inlet/SphinxWriter.hpp @@ -145,6 +145,7 @@ class SphinxWriter : public Writer bool isSelectedElement; std::vector> fieldTable; std::vector> functionTable; + std::vector> childContainers; }; /*! From 05f390bf6c7f171e344c2a684b1c4b684805baef Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Tue, 23 Mar 2021 11:08:27 -0500 Subject: [PATCH 03/12] fix: ignore pindividual fields of primitive collections, don't hyperlink trivial subcontainers --- src/axom/inlet/SphinxWriter.cpp | 43 +++++++++++++++++++++++++++------ src/axom/inlet/SphinxWriter.hpp | 12 ++++++++- 2 files changed, 46 insertions(+), 9 deletions(-) diff --git a/src/axom/inlet/SphinxWriter.cpp b/src/axom/inlet/SphinxWriter.cpp index 68e0687235..3da953f9ab 100644 --- a/src/axom/inlet/SphinxWriter.cpp +++ b/src/axom/inlet/SphinxWriter.cpp @@ -114,6 +114,16 @@ void SphinxWriter::documentContainer(const Container& container) currContainer.description = sidreGroup->getView("description")->getString(); } + // Bail out if this is a collection of primitives - + // it doesn't make sense to document each individual primitive + // FIXME: Implement something analogous to the logic for struct collections that displays the + // "schema" for the primitive elements of the collection + if(isCollectionGroup(container.name()) && + !sidreGroup->hasView(detail::STRUCT_COLLECTION_FLAG)) + { + return; + } + for(const auto& field_entry : container.getChildFields()) { extractFieldMetadata(field_entry.second->sidreGroup(), currContainer); @@ -129,18 +139,26 @@ void SphinxWriter::documentContainer(const Container& container) { for(const auto& container_entry : container.getChildContainers()) { - if(!isCollectionGroup(container_entry.first) && - !detail::isTrivial(*container_entry.second)) + if(!isCollectionGroup(container_entry.first)) { const auto name = removeBeforeDelimiter(container_entry.first); std::string description; - if(container_entry.second->sidreGroup()->hasView("description")) + const auto group = container_entry.second->sidreGroup(); + const static auto collectionDescriptionPath = + appendPrefix(detail::COLLECTION_GROUP_NAME, "description"); + if(group->hasView("description")) + { + description = group->getView("description")->getString(); + } + else if(group->hasView(collectionDescriptionPath)) { - description = - container_entry.second->sidreGroup()->getView("description")->getString(); + // If the label is applied to the collection group itself, we can use that instead + description = group->getView(collectionDescriptionPath)->getString(); } currContainer.childContainers.push_back( - {std::move(name), std::move(description)}); + {std::move(name), + std::move(description), + detail::isTrivial(*container_entry.second)}); } } } @@ -277,8 +295,17 @@ void SphinxWriter::writeNestedTables() // FIXME: Would it be useful to alphabetize these?? for(const auto& container : containers) { - m_oss << fmt::format(" * - `{0}`_\n", container.first); - m_oss << fmt::format(" - {0}\n", container.second); + // We can set up a hyperlink to non-trivial tables because they will + // be subsequently documented + if(container.isTrivial) + { + m_oss << fmt::format(" * - {0}\n", container.name); + } + else + { + m_oss << fmt::format(" * - `{0}`_\n", container.name); + } + m_oss << fmt::format(" - {0}\n", container.description); } // Need to skip first element (header row), hence no range-based for loop diff --git a/src/axom/inlet/SphinxWriter.hpp b/src/axom/inlet/SphinxWriter.hpp index 5a12bc519e..eafbd29c0f 100644 --- a/src/axom/inlet/SphinxWriter.hpp +++ b/src/axom/inlet/SphinxWriter.hpp @@ -145,7 +145,17 @@ class SphinxWriter : public Writer bool isSelectedElement; std::vector> fieldTable; std::vector> functionTable; - std::vector> childContainers; + /** + * \brief Stores a minimal set of data about child containers + * Used only for the table of contents in nested "mode" + */ + struct ChildContainerData + { + std::string name; + std::string description; + bool isTrivial; + }; + std::vector childContainers; }; /*! From 94365eeb88a68a39fab70dd4f5195a6656ef1f1d Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Tue, 23 Mar 2021 13:06:13 -0500 Subject: [PATCH 04/12] docs: add copyright to inlet docs and add writer page --- src/axom/inlet/docs/sphinx/advanced_types.rst | 5 +++++ src/axom/inlet/docs/sphinx/functions.rst | 5 +++++ src/axom/inlet/docs/sphinx/index.rst | 4 ++++ src/axom/inlet/docs/sphinx/quick_start.rst | 7 +++++++ src/axom/inlet/docs/sphinx/readers.rst | 5 +++++ src/axom/inlet/docs/sphinx/simple_types.rst | 5 +++++ src/axom/inlet/docs/sphinx/verification.rst | 5 +++++ src/axom/inlet/docs/sphinx/writers.rst | 13 +++++++++++++ 8 files changed, 49 insertions(+) create mode 100644 src/axom/inlet/docs/sphinx/writers.rst diff --git a/src/axom/inlet/docs/sphinx/advanced_types.rst b/src/axom/inlet/docs/sphinx/advanced_types.rst index 953657cf13..3b1f0dd345 100644 --- a/src/axom/inlet/docs/sphinx/advanced_types.rst +++ b/src/axom/inlet/docs/sphinx/advanced_types.rst @@ -1,3 +1,8 @@ +.. ## Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and +.. ## other Axom Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + .. _inlet_advanced_types_label: ############## diff --git a/src/axom/inlet/docs/sphinx/functions.rst b/src/axom/inlet/docs/sphinx/functions.rst index f250667b09..3c1f45c23c 100644 --- a/src/axom/inlet/docs/sphinx/functions.rst +++ b/src/axom/inlet/docs/sphinx/functions.rst @@ -1,3 +1,8 @@ +.. ## Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and +.. ## other Axom Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + ################## Function Callbacks ################## diff --git a/src/axom/inlet/docs/sphinx/index.rst b/src/axom/inlet/docs/sphinx/index.rst index 32d57e6f8b..c3e8e4a671 100644 --- a/src/axom/inlet/docs/sphinx/index.rst +++ b/src/axom/inlet/docs/sphinx/index.rst @@ -1,3 +1,7 @@ +.. ## Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and +.. ## other Axom Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) Inlet User Guide ================ diff --git a/src/axom/inlet/docs/sphinx/quick_start.rst b/src/axom/inlet/docs/sphinx/quick_start.rst index bbb3110008..92f5e79d4c 100644 --- a/src/axom/inlet/docs/sphinx/quick_start.rst +++ b/src/axom/inlet/docs/sphinx/quick_start.rst @@ -1,3 +1,8 @@ +.. ## Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and +.. ## other Axom Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + .. _inlet_quick_start_label: Quick Start @@ -142,3 +147,5 @@ Using the same ``documentation_generation.cpp`` example, the automatically gene with input file writing: .. image:: json_schema_example.gif + +For a full description of Inlet's ``Writer`` implementations, see :ref:`Writers `. diff --git a/src/axom/inlet/docs/sphinx/readers.rst b/src/axom/inlet/docs/sphinx/readers.rst index 70c971efde..db40e04c4a 100644 --- a/src/axom/inlet/docs/sphinx/readers.rst +++ b/src/axom/inlet/docs/sphinx/readers.rst @@ -1,3 +1,8 @@ +.. ## Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and +.. ## other Axom Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + ####### Readers ####### diff --git a/src/axom/inlet/docs/sphinx/simple_types.rst b/src/axom/inlet/docs/sphinx/simple_types.rst index 2ee7f98953..5e70d7ba58 100644 --- a/src/axom/inlet/docs/sphinx/simple_types.rst +++ b/src/axom/inlet/docs/sphinx/simple_types.rst @@ -1,3 +1,8 @@ +.. ## Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and +.. ## other Axom Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + ############ Simple Types ############ diff --git a/src/axom/inlet/docs/sphinx/verification.rst b/src/axom/inlet/docs/sphinx/verification.rst index c480cbb74b..fd36127de3 100644 --- a/src/axom/inlet/docs/sphinx/verification.rst +++ b/src/axom/inlet/docs/sphinx/verification.rst @@ -1,3 +1,8 @@ +.. ## Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and +.. ## other Axom Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + .. _inlet_verification_page_label: ############ diff --git a/src/axom/inlet/docs/sphinx/writers.rst b/src/axom/inlet/docs/sphinx/writers.rst new file mode 100644 index 0000000000..8b8c2a4eb8 --- /dev/null +++ b/src/axom/inlet/docs/sphinx/writers.rst @@ -0,0 +1,13 @@ +.. ## Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and +.. ## other Axom Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + +.. _inlet_writer_page_label: + +####### +Writers +####### + +Inlet provides a ``Writer`` interface for exporting metadata once the input file has been read in +and the schema has been defined. From 2fb4c64aaf9711fe886334236d2e7e4189d8c8a7 Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Tue, 23 Mar 2021 16:18:46 -0500 Subject: [PATCH 05/12] docs: reorganize docs to provide examples of both sphinx modes --- .../sphinx/example1_nested_documentation.rst | 279 ++++++++++++++++++ ...n.rst => example1_table_documentation.rst} | 6 +- src/axom/inlet/docs/sphinx/index.rst | 1 + ... mfem_coefficient_table_documentation.rst} | 0 .../nested_structs_nested_documentatiom.rst | 235 +++++++++++++++ ...=> nested_structs_table_documentation.rst} | 6 +- src/axom/inlet/docs/sphinx/quick_start.rst | 25 +- src/axom/inlet/docs/sphinx/writers.rst | 53 ++++ 8 files changed, 577 insertions(+), 28 deletions(-) create mode 100644 src/axom/inlet/docs/sphinx/example1_nested_documentation.rst rename src/axom/inlet/docs/sphinx/{example1_expected_documentation.rst => example1_table_documentation.rst} (89%) rename src/axom/inlet/docs/sphinx/{mfem_coefficient_expected_documentation.rst => mfem_coefficient_table_documentation.rst} (100%) create mode 100644 src/axom/inlet/docs/sphinx/nested_structs_nested_documentatiom.rst rename src/axom/inlet/docs/sphinx/{nested_structs_expected_documentation.rst => nested_structs_table_documentation.rst} (94%) diff --git a/src/axom/inlet/docs/sphinx/example1_nested_documentation.rst b/src/axom/inlet/docs/sphinx/example1_nested_documentation.rst new file mode 100644 index 0000000000..bc650d5298 --- /dev/null +++ b/src/axom/inlet/docs/sphinx/example1_nested_documentation.rst @@ -0,0 +1,279 @@ +.. |uncheck| unicode:: U+2610 .. UNCHECKED BOX +.. |check| unicode:: U+2611 .. CHECKED BOX + +================================================ +Example Output: Input File Options (nested mode) +================================================ + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `thermal_solver`_ + - + + + +-------------- +thermal_solver +-------------- + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `solver`_ + - linear equation solver options + * - `kappa`_ + - + * - `u0`_ + - + * - `mesh`_ + - + * - `timestepper`_ + - thermal solver timestepper + * - `order`_ + - polynomial order + + +.. _timestepper: + +**timestepper** + +thermal solver timestepper + + - Default value: quasistatic + - Valid values: quasistatic, forwardeuler, backwardeuler + - Optional + + +.. _order: + +**order** + +polynomial order + + - Valid values: 1 to 2147483647 + - Optional + + + +------ +solver +------ + +linear equation solver options + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `dt`_ + - time step + * - `max_iter`_ + - maximum iteration limit + * - `print_level`_ + - solver print/debug level + * - `abs_tol`_ + - solver absolute tolerance + * - `steps`_ + - number of steps/cycles to take + * - `rel_tol`_ + - solver relative tolerance + + +.. _dt: + +**dt** + +time step + + - Default value: 1.000000 + - Valid values: 0.000e+00 to 1.798e+308 + - Optional + + +.. _max_iter: + +**max_iter** + +maximum iteration limit + + - Default value: 100 + - Valid values: 1 to 2147483647 + - Optional + + +.. _print_level: + +**print_level** + +solver print/debug level + + - Default value: 0 + - Valid values: 0 to 3 + - Optional + + +.. _abs_tol: + +**abs_tol** + +solver absolute tolerance + + - Default value: 0.000000 + - Valid values: 0.000e+00 to 1.798e+308 + - Optional + + +.. _steps: + +**steps** + +number of steps/cycles to take + + - Default value: 1 + - Valid values: 1 to 2147483647 + - Optional + + +.. _rel_tol: + +**rel_tol** + +solver relative tolerance + + - Default value: 0.000001 + - Valid values: 0.000e+00 to 1.798e+308 + - Optional + + + +----- +kappa +----- + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `constant`_ + - thermal conductivity constant + * - `type`_ + - description for kappa type + + +.. _constant: + +**constant** + +thermal conductivity constant + + + +.. _type: + +**type** + +description for kappa type + + - Valid values: constant, function + - Optional + + + +-- +u0 +-- + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `func`_ + - description for u0 func + * - `type`_ + - description for u0 type + + +.. _func: + +**func** + +description for u0 func + + + +.. _type: + +**type** + +description for u0 type + + - Default value: constant + - Valid values: constant, function + - Optional + + + +---- +mesh +---- + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `parallel`_ + - + * - `serial`_ + - number of serial refinements + * - `filename`_ + - mesh filename + + +.. _parallel: + +**parallel** + + + + - Default value: 1 + - Valid values: 1 to 2147483647 + - Optional + + +.. _serial: + +**serial** + +number of serial refinements + + - Default value: 1 + - Valid values: 0 to 2147483647 + - Optional + + +.. _filename: + +**filename** + +mesh filename diff --git a/src/axom/inlet/docs/sphinx/example1_expected_documentation.rst b/src/axom/inlet/docs/sphinx/example1_table_documentation.rst similarity index 89% rename from src/axom/inlet/docs/sphinx/example1_expected_documentation.rst rename to src/axom/inlet/docs/sphinx/example1_table_documentation.rst index 4c8eb6d25c..216caaf252 100644 --- a/src/axom/inlet/docs/sphinx/example1_expected_documentation.rst +++ b/src/axom/inlet/docs/sphinx/example1_table_documentation.rst @@ -1,9 +1,9 @@ .. |uncheck| unicode:: U+2610 .. UNCHECKED BOX .. |check| unicode:: U+2611 .. CHECKED BOX -================== -Example Output: Input File Options -================== +=============================================== +Example Output: Input File Options (table mode) +=============================================== -------------- thermal_solver diff --git a/src/axom/inlet/docs/sphinx/index.rst b/src/axom/inlet/docs/sphinx/index.rst index c3e8e4a671..7ee850b61e 100644 --- a/src/axom/inlet/docs/sphinx/index.rst +++ b/src/axom/inlet/docs/sphinx/index.rst @@ -62,6 +62,7 @@ Glossary quick_start readers + writers simple_types advanced_types functions diff --git a/src/axom/inlet/docs/sphinx/mfem_coefficient_expected_documentation.rst b/src/axom/inlet/docs/sphinx/mfem_coefficient_table_documentation.rst similarity index 100% rename from src/axom/inlet/docs/sphinx/mfem_coefficient_expected_documentation.rst rename to src/axom/inlet/docs/sphinx/mfem_coefficient_table_documentation.rst diff --git a/src/axom/inlet/docs/sphinx/nested_structs_nested_documentatiom.rst b/src/axom/inlet/docs/sphinx/nested_structs_nested_documentatiom.rst new file mode 100644 index 0000000000..562cd85fd2 --- /dev/null +++ b/src/axom/inlet/docs/sphinx/nested_structs_nested_documentatiom.rst @@ -0,0 +1,235 @@ +.. |uncheck| unicode:: U+2610 .. UNCHECKED BOX +.. |check| unicode:: U+2611 .. CHECKED BOX + +======================================================= +Nested Structs Output: Input file Options (nested mode) +======================================================= + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `shapes`_ + - + + + +------ +shapes +------ + + + + +-------------------- +Collection contents: +-------------------- + + + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `geometry`_ + - Geometric information on the shape + * - `material`_ + - Material of the shape + * - `name`_ + - Name of the shape + + +.. _material: + +**material** + +Material of the shape + + - Valid values: steel, wood, plastic + - Optional + + +.. _name: + +**name** + +Name of the shape + + + + +-------- +geometry +-------- + +Geometric information on the shape + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `operators`_ + - List of shape operations to apply + * - `start_dimensions`_ + - Dimension in which to begin applying operations + * - `units`_ + - Units for length + * - `path`_ + - Path to the shape file + * - `format`_ + - File format for the shape + + +.. _start_dimensions: + +**start_dimensions** + +Dimension in which to begin applying operations + + - Default value: 3 + + +.. _units: + +**units** + +Units for length + + - Default value: cm + - Valid values: cm, m + - Optional + + +.. _path: + +**path** + +Path to the shape file + + + +.. _format: + +**format** + +File format for the shape + + + + +--------- +operators +--------- + + + + +-------------------- +Collection contents: +-------------------- + +List of shape operations to apply + + + +List of shape operations to apply + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `slice`_ + - Options for a slice operation + * - center + - Center of rotation + * - `translate`_ + - Translation vector + * - axis + - Axis on which to rotate + * - `rotate`_ + - Degrees of rotation + + +.. _rotate: + +**rotate** + +Degrees of rotation + + - Valid values: -1.800e+02 to 1.800e+02 + - Optional + + + +----- +slice +----- + +Options for a slice operation + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - origin + - Origin for the slice operation + * - `z`_ + - z-axis point to slice on + * - `y`_ + - y-axis point to slice on + * - `x`_ + - x-axis point to slice on + + +.. _z: + +**z** + +z-axis point to slice on + + + +.. _y: + +**y** + +y-axis point to slice on + + + +.. _x: + +**x** + +x-axis point to slice on + + + + +--------- +translate +--------- + + + + +-------------------- +Collection contents: +-------------------- + +Translation vector diff --git a/src/axom/inlet/docs/sphinx/nested_structs_expected_documentation.rst b/src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst similarity index 94% rename from src/axom/inlet/docs/sphinx/nested_structs_expected_documentation.rst rename to src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst index f5d1eb5e2a..46d685c320 100644 --- a/src/axom/inlet/docs/sphinx/nested_structs_expected_documentation.rst +++ b/src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst @@ -1,9 +1,9 @@ .. |uncheck| unicode:: U+2610 .. UNCHECKED BOX .. |check| unicode:: U+2611 .. CHECKED BOX -========================================= -Nested Structs Output: Input file Options -========================================= +====================================================== +Nested Structs Output: Input file Options (table mode) +====================================================== ------ shapes diff --git a/src/axom/inlet/docs/sphinx/quick_start.rst b/src/axom/inlet/docs/sphinx/quick_start.rst index 92f5e79d4c..f3c6abb65b 100644 --- a/src/axom/inlet/docs/sphinx/quick_start.rst +++ b/src/axom/inlet/docs/sphinx/quick_start.rst @@ -111,7 +111,7 @@ Generating Documentation ------------------------ We provide a slightly more complex but closer to a real world Inlet usage example of the usage of Inlet. -You can find that example in our repository `here `_. +You can find that example in our repository `here `_. After you create your ``Inlet`` class but before you start defining your schema, create a concrete instantiation of a ``Writer`` class and register it with your ``Inlet`` class. @@ -128,24 +128,5 @@ to write out your documentation to the given file. inlet.write(); -We provided a basic Sphinx documentation writing class but you may want to customize it to your -own style. The link below shows the example output from the ``documentation_generation.cpp`` example: - -.. toctree:: - :maxdepth: 1 - - example1_expected_documentation - mfem_coefficient_expected_documentation - nested_structs_expected_documentation - -Inlet also provides a utility for generating a `JSON schema `_ from your input file schema. -This allows for integration with text editors like Visual Studio Code, which allows you to associate a JSON schema -with an input file and subsequently provides autocompletion, linting, tooltips, and more. VSCode and other editors -currently support verification of JSON and YAML input files with JSON schemas. - -Using the same ``documentation_generation.cpp`` example, the automatically generated schema can be used to assist -with input file writing: - -.. image:: json_schema_example.gif - -For a full description of Inlet's ``Writer`` implementations, see :ref:`Writers `. +Inlet provides a few basic options but you can also implement a custom ``Writer`` that fits your own style. +For a full description of Inlet's ``Writer`` interface and implementations, see :ref:`Writers `. diff --git a/src/axom/inlet/docs/sphinx/writers.rst b/src/axom/inlet/docs/sphinx/writers.rst index 8b8c2a4eb8..878cd3781c 100644 --- a/src/axom/inlet/docs/sphinx/writers.rst +++ b/src/axom/inlet/docs/sphinx/writers.rst @@ -11,3 +11,56 @@ Writers Inlet provides a ``Writer`` interface for exporting metadata once the input file has been read in and the schema has been defined. + +Inlet also provides a few implementations of this interface: + +------ +Sphinx +------ + +The ``SphinxWriter`` generates a `reStructuredText `_ (.rst) file +compatible with the `Sphinx `_ documentation tool. + +The ``SphinxWriter`` currently has two styles available: + +- A table-based style that, for each ``Container``, generates a table for its child fields and functions +- A nested style that includes a "table of contents" for each ``Container`` with links to full descriptions + of child fields and functions + +For comparison, the following is produced from the ``documentation_generation.cpp`` example: + +.. toctree:: + :maxdepth: 1 + + example1_table_documentation + example1_nested_documentation + +...from the ``mfem_coefficient.cpp`` example: + +.. toctree:: + :maxdepth: 1 + + mfem_coefficient_table_documentation + mfem_coefficient_nested_documentation + +...and from the ``nested_structs.cpp`` example: + +.. toctree:: + :maxdepth: 1 + + nested_structs_table_documentation + nested_structs_nested_documentatiom + +----------- +JSON Schema +----------- + +Inlet also provides a utility for generating a `JSON schema `_ from your input file schema. +This allows for integration with text editors like Visual Studio Code, which allows you to associate a JSON schema +with an input file and subsequently provides autocompletion, linting, tooltips, and more. VSCode and other editors +currently support verification of JSON and YAML input files with JSON schemas. + +Using the same ``documentation_generation.cpp`` example, the automatically generated schema can be used to assist +with input file writing: + +.. image:: json_schema_example.gif From e06d1fed084b758c58beca32f8def01cd6b0cea3 Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Tue, 23 Mar 2021 17:13:35 -0500 Subject: [PATCH 06/12] cleanup: add style and title selection options for the SphinxWriter --- src/axom/inlet/SphinxWriter.cpp | 51 ++++++++++-- src/axom/inlet/SphinxWriter.hpp | 19 ++++- .../mfem_coefficient_nested_documentation.rst | 83 +++++++++++++++++++ .../mfem_coefficient_table_documentation.rst | 32 +------ ...> nested_structs_nested_documentation.rst} | 6 +- .../nested_structs_table_documentation.rst | 32 +------ src/axom/inlet/docs/sphinx/writers.rst | 2 +- src/axom/inlet/examples/mfem_coefficient.cpp | 2 +- src/axom/inlet/examples/nested_structs.cpp | 2 +- 9 files changed, 159 insertions(+), 70 deletions(-) create mode 100644 src/axom/inlet/docs/sphinx/mfem_coefficient_nested_documentation.rst rename src/axom/inlet/docs/sphinx/{nested_structs_nested_documentatiom.rst => nested_structs_nested_documentation.rst} (94%) diff --git a/src/axom/inlet/SphinxWriter.cpp b/src/axom/inlet/SphinxWriter.cpp index 3da953f9ab..d52cdd0580 100644 --- a/src/axom/inlet/SphinxWriter.cpp +++ b/src/axom/inlet/SphinxWriter.cpp @@ -58,7 +58,9 @@ constexpr typename std::underlying_type::type to_underlying(const E e) } // namespace detail -SphinxWriter::SphinxWriter(const std::string& fileName) +SphinxWriter::SphinxWriter(const std::string& fileName, + const std::string& title, + const Style style) : m_fieldColLabels({"Field Name", "Description", "Default Value", @@ -66,11 +68,19 @@ SphinxWriter::SphinxWriter(const std::string& fileName) "Required"}) , m_functionColLabels( {"Function Name", "Description", "Signature", "Required"}) + , m_style(style) { m_fileName = fileName; m_oss << ".. |uncheck| unicode:: U+2610 .. UNCHECKED BOX\n"; m_oss << ".. |check| unicode:: U+2611 .. CHECKED BOX\n\n"; - writeTitle("Input file Options"); + if(title.empty()) + { + writeTitle("Input file Options"); + } + else + { + writeTitle(title); + } } void SphinxWriter::documentContainer(const Container& container) @@ -166,8 +176,14 @@ void SphinxWriter::documentContainer(const Container& container) void SphinxWriter::finalize() { - // writeAllTables(); - writeNestedTables(); + if(m_style == Style::Nested) + { + writeNestedTables(); + } + else + { + writeAllTables(); + } m_outFile.open(m_fileName); m_outFile << m_oss.str(); m_outFile.close(); @@ -338,13 +354,38 @@ void SphinxWriter::writeNestedTables() } // Whether it's required - if(!fieldData[3].empty()) + if(!fieldData[4].empty()) { const bool isRequired = fieldData[3] == "|check|"; m_oss << fmt::format(" - {0}\n", isRequired ? "Required" : "Optional"); } m_oss << "\n\n"; }); + + std::for_each( + functions.begin() + 1, + functions.end(), + [this](const std::vector& functionData) { + // Insert a hyperlink target for the name + m_oss << fmt::format(".. _{0}:\n\n", functionData[0]); + m_oss << fmt::format("**{0}**\n\n", functionData[0]); // name + // description - ideally this would be an extended description + m_oss << functionData[1] << "\n\n"; + + // The function's signature + if(!functionData[2].empty()) + { + m_oss << fmt::format(" - Signature: {0}\n", functionData[2]); + } + + // Whether it's required + if(!functionData[3].empty()) + { + const bool isRequired = functionData[3] == "|check|"; + m_oss << fmt::format(" - {0}\n", isRequired ? "Required" : "Optional"); + } + m_oss << "\n\n"; + }); } } diff --git a/src/axom/inlet/SphinxWriter.hpp b/src/axom/inlet/SphinxWriter.hpp index eafbd29c0f..9df1bb01b2 100644 --- a/src/axom/inlet/SphinxWriter.hpp +++ b/src/axom/inlet/SphinxWriter.hpp @@ -39,14 +39,30 @@ namespace inlet class SphinxWriter : public Writer { public: + /*! + ******************************************************************************* + * \brief Supported phinx style options + ******************************************************************************* + */ + enum class Style + { + // FIXME: These names are not clear at all + Table, // Tables for the child Fields/Functions of each Container + Nested // Table of contents for each Container, then sections for each child + }; + /*! ******************************************************************************* * \brief A constructor for SphinxWriter. * * \param [in] fileName The name of the file the documentation should be written to. + * \param [in] title The title of the generated rst file + * \param [in] style The style of docs to generate ******************************************************************************* */ - SphinxWriter(const std::string& fileName); + SphinxWriter(const std::string& fileName, + const std::string& title = {}, + const Style style = Style::Table); void documentContainer(const Container& container) override; @@ -262,6 +278,7 @@ class SphinxWriter : public Writer std::vector m_fieldColLabels; // Used for the RST tables for functions std::vector m_functionColLabels; + Style m_style; }; } // namespace inlet diff --git a/src/axom/inlet/docs/sphinx/mfem_coefficient_nested_documentation.rst b/src/axom/inlet/docs/sphinx/mfem_coefficient_nested_documentation.rst new file mode 100644 index 0000000000..bdd4753c6a --- /dev/null +++ b/src/axom/inlet/docs/sphinx/mfem_coefficient_nested_documentation.rst @@ -0,0 +1,83 @@ +.. |uncheck| unicode:: U+2610 .. UNCHECKED BOX +.. |check| unicode:: U+2611 .. CHECKED BOX + +===================================== +MFEM Coefficient Output (nested mode) +===================================== +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `bcs`_ + - List of boundary conditions + + + +--- +bcs +--- + + + + +-------------------- +Collection contents: +-------------------- + +List of boundary conditions + + + +List of boundary conditions + +.. list-table:: + :widths: 25 50 + :header-rows: 1 + :stub-columns: 1 + + * - Name + - Description + * - `attrs`_ + - List of boundary attributes + * - `coef`_ + - The function representing the BC coefficient + * - `vec_coef`_ + - The function representing the BC coefficient + + +.. _coef: + +**coef** + +The function representing the BC coefficient + + - Signature: Double(Vector, Double) + - Optional + + +.. _vec_coef: + +**vec_coef** + +The function representing the BC coefficient + + - Signature: Vector(Vector, Double) + - Optional + + + +----- +attrs +----- + + + + +-------------------- +Collection contents: +-------------------- + +List of boundary attributes diff --git a/src/axom/inlet/docs/sphinx/mfem_coefficient_table_documentation.rst b/src/axom/inlet/docs/sphinx/mfem_coefficient_table_documentation.rst index eb14372777..eaf47e4aa8 100644 --- a/src/axom/inlet/docs/sphinx/mfem_coefficient_table_documentation.rst +++ b/src/axom/inlet/docs/sphinx/mfem_coefficient_table_documentation.rst @@ -1,9 +1,9 @@ .. |uncheck| unicode:: U+2610 .. UNCHECKED BOX .. |check| unicode:: U+2611 .. CHECKED BOX -=========================================== -MFEM Coefficient Output: Input file Options -=========================================== +==================================== +MFEM Coefficient Output (table mode) +==================================== --- bcs @@ -47,29 +47,3 @@ Collection contents: -------------------- Description: List of boundary attributes - -.. list-table:: Fields - :widths: 25 25 25 25 25 - :header-rows: 1 - :stub-columns: 1 - - * - Field Name - - Description - - Default Value - - Range/Valid Values - - Required - * - 1 - - - - - - - - |uncheck| - * - 2 - - - - - - - - |uncheck| - * - 3 - - - - - - - - |uncheck| diff --git a/src/axom/inlet/docs/sphinx/nested_structs_nested_documentatiom.rst b/src/axom/inlet/docs/sphinx/nested_structs_nested_documentation.rst similarity index 94% rename from src/axom/inlet/docs/sphinx/nested_structs_nested_documentatiom.rst rename to src/axom/inlet/docs/sphinx/nested_structs_nested_documentation.rst index 562cd85fd2..19b5df2f00 100644 --- a/src/axom/inlet/docs/sphinx/nested_structs_nested_documentatiom.rst +++ b/src/axom/inlet/docs/sphinx/nested_structs_nested_documentation.rst @@ -1,9 +1,9 @@ .. |uncheck| unicode:: U+2610 .. UNCHECKED BOX .. |check| unicode:: U+2611 .. CHECKED BOX -======================================================= -Nested Structs Output: Input file Options (nested mode) -======================================================= +=================================== +Nested Structs Output (nested mode) +=================================== .. list-table:: :widths: 25 50 diff --git a/src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst b/src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst index 46d685c320..f1d0085ba0 100644 --- a/src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst +++ b/src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst @@ -1,9 +1,9 @@ .. |uncheck| unicode:: U+2610 .. UNCHECKED BOX .. |check| unicode:: U+2611 .. CHECKED BOX -====================================================== -Nested Structs Output: Input file Options (table mode) -====================================================== +================================== +Nested Structs Output (table mode) +================================== ------ shapes @@ -147,29 +147,3 @@ Collection contents: -------------------- Description: Translation vector - -.. list-table:: Fields - :widths: 25 25 25 25 25 - :header-rows: 1 - :stub-columns: 1 - - * - Field Name - - Description - - Default Value - - Range/Valid Values - - Required - * - 0 - - - - - - - - |uncheck| - * - 1 - - - - - - - - |uncheck| - * - 2 - - - - - - - - |uncheck| diff --git a/src/axom/inlet/docs/sphinx/writers.rst b/src/axom/inlet/docs/sphinx/writers.rst index 878cd3781c..7d96705ac6 100644 --- a/src/axom/inlet/docs/sphinx/writers.rst +++ b/src/axom/inlet/docs/sphinx/writers.rst @@ -49,7 +49,7 @@ For comparison, the following is produced from the ``documentation_generation.cp :maxdepth: 1 nested_structs_table_documentation - nested_structs_nested_documentatiom + nested_structs_nested_documentation ----------- JSON Schema diff --git a/src/axom/inlet/examples/mfem_coefficient.cpp b/src/axom/inlet/examples/mfem_coefficient.cpp index a9171da0de..c49e00821d 100644 --- a/src/axom/inlet/examples/mfem_coefficient.cpp +++ b/src/axom/inlet/examples/mfem_coefficient.cpp @@ -235,7 +235,7 @@ int main(int argc, char** argv) { const std::string docFileName = "mfem_coefficient.rst"; std::unique_ptr writer( - new inlet::SphinxWriter(docFileName)); + new inlet::SphinxWriter(docFileName, "MFEM Coefficient Output")); inlet.registerWriter(std::move(writer)); inlet.write(); SLIC_INFO("Documentation was written to " << docFileName); diff --git a/src/axom/inlet/examples/nested_structs.cpp b/src/axom/inlet/examples/nested_structs.cpp index f0a21e1685..545dbd52c4 100644 --- a/src/axom/inlet/examples/nested_structs.cpp +++ b/src/axom/inlet/examples/nested_structs.cpp @@ -346,7 +346,7 @@ int main(int argc, char** argv) { const std::string docFileName = "nested_structs"; std::unique_ptr sphinxWriter( - new inlet::SphinxWriter(docFileName + ".rst")); + new inlet::SphinxWriter(docFileName + ".rst", "Nested Structs Output")); inlet.registerWriter(std::move(sphinxWriter)); inlet.write(); std::unique_ptr schemaWriter( From e2a60fa46aff78d4c4c79ec05a2a9f80002dede7 Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Thu, 8 Apr 2021 13:01:58 -0500 Subject: [PATCH 07/12] fix: avoid duplicated hyperlinks by using container index --- src/axom/inlet/SphinxWriter.cpp | 16 +++-- .../sphinx/example1_nested_documentation.rst | 68 ++++++++++--------- 2 files changed, 45 insertions(+), 39 deletions(-) diff --git a/src/axom/inlet/SphinxWriter.cpp b/src/axom/inlet/SphinxWriter.cpp index 6e47b20f10..932e469c84 100644 --- a/src/axom/inlet/SphinxWriter.cpp +++ b/src/axom/inlet/SphinxWriter.cpp @@ -271,6 +271,8 @@ void SphinxWriter::writeAllTables() void SphinxWriter::writeNestedTables() { + // Used to avoid duplicate hyperlinks + int containerCount = 0; for(const auto& pathName : m_inletContainerPathNames) { const auto& currContainer = m_rstTables.at(pathName); @@ -302,9 +304,10 @@ void SphinxWriter::writeNestedTables() // Writes a name + description to the "table of contents" // for each Container - auto writeTOCEntry = [this](const std::vector& data) { + auto writeTOCEntry = [this, + containerCount](const std::vector& data) { // FIXME: Overlapping link names? Need to use the full path or a hash?? - m_oss << fmt::format(" * - `{0}`_\n", data[0]); + m_oss << fmt::format(" * - :ref:`{0}<{0}{1}>`\n", data[0], containerCount); m_oss << fmt::format(" - {0}\n", data[1]); }; @@ -334,9 +337,9 @@ void SphinxWriter::writeNestedTables() std::for_each( fields.begin() + 1, fields.end(), - [this](const std::vector& fieldData) { + [this, containerCount](const std::vector& fieldData) { // Insert a hyperlink target for the name - m_oss << fmt::format(".. _{0}:\n\n", fieldData[0]); + m_oss << fmt::format(".. _{0}{1}:\n\n", fieldData[0], containerCount); m_oss << fmt::format("**{0}**\n\n", fieldData[0]); // name // description - ideally this would be an extended description m_oss << fieldData[1] << "\n\n"; @@ -365,9 +368,9 @@ void SphinxWriter::writeNestedTables() std::for_each( functions.begin() + 1, functions.end(), - [this](const std::vector& functionData) { + [this, containerCount](const std::vector& functionData) { // Insert a hyperlink target for the name - m_oss << fmt::format(".. _{0}:\n\n", functionData[0]); + m_oss << fmt::format(".. _{0}{1}:\n\n", functionData[0], containerCount); m_oss << fmt::format("**{0}**\n\n", functionData[0]); // name // description - ideally this would be an extended description m_oss << functionData[1] << "\n\n"; @@ -386,6 +389,7 @@ void SphinxWriter::writeNestedTables() } m_oss << "\n\n"; }); + containerCount++; } } diff --git a/src/axom/inlet/docs/sphinx/example1_nested_documentation.rst b/src/axom/inlet/docs/sphinx/example1_nested_documentation.rst index bc650d5298..08a6981577 100644 --- a/src/axom/inlet/docs/sphinx/example1_nested_documentation.rst +++ b/src/axom/inlet/docs/sphinx/example1_nested_documentation.rst @@ -29,20 +29,20 @@ thermal_solver * - Name - Description * - `solver`_ - - linear equation solver options + - * - `kappa`_ - * - `u0`_ - * - `mesh`_ - - * - `timestepper`_ + * - :ref:`timestepper` - thermal solver timestepper - * - `order`_ + * - :ref:`order` - polynomial order -.. _timestepper: +.. _timestepper1: **timestepper** @@ -53,7 +53,7 @@ thermal solver timestepper - Optional -.. _order: +.. _order1: **order** @@ -68,8 +68,6 @@ polynomial order solver ------ -linear equation solver options - .. list-table:: :widths: 25 50 :header-rows: 1 @@ -77,21 +75,21 @@ linear equation solver options * - Name - Description - * - `dt`_ + * - :ref:`dt` - time step - * - `max_iter`_ + * - :ref:`max_iter` - maximum iteration limit - * - `print_level`_ + * - :ref:`print_level` - solver print/debug level - * - `abs_tol`_ + * - :ref:`abs_tol` - solver absolute tolerance - * - `steps`_ + * - :ref:`steps` - number of steps/cycles to take - * - `rel_tol`_ + * - :ref:`rel_tol` - solver relative tolerance -.. _dt: +.. _dt2: **dt** @@ -102,7 +100,7 @@ time step - Optional -.. _max_iter: +.. _max_iter2: **max_iter** @@ -113,7 +111,7 @@ maximum iteration limit - Optional -.. _print_level: +.. _print_level2: **print_level** @@ -124,7 +122,7 @@ solver print/debug level - Optional -.. _abs_tol: +.. _abs_tol2: **abs_tol** @@ -135,7 +133,7 @@ solver absolute tolerance - Optional -.. _steps: +.. _steps2: **steps** @@ -146,7 +144,7 @@ number of steps/cycles to take - Optional -.. _rel_tol: +.. _rel_tol2: **rel_tol** @@ -169,21 +167,22 @@ kappa * - Name - Description - * - `constant`_ + * - :ref:`constant` - thermal conductivity constant - * - `type`_ + * - :ref:`type` - description for kappa type -.. _constant: +.. _constant3: **constant** thermal conductivity constant + - Optional -.. _type: +.. _type3: **type** @@ -205,21 +204,22 @@ u0 * - Name - Description - * - `func`_ + * - :ref:`func` - description for u0 func - * - `type`_ + * - :ref:`type` - description for u0 type -.. _func: +.. _func4: **func** description for u0 func + - Optional -.. _type: +.. _type4: **type** @@ -242,15 +242,15 @@ mesh * - Name - Description - * - `parallel`_ + * - :ref:`parallel` - - * - `serial`_ + * - :ref:`serial` - number of serial refinements - * - `filename`_ + * - :ref:`filename` - mesh filename -.. _parallel: +.. _parallel5: **parallel** @@ -261,7 +261,7 @@ mesh - Optional -.. _serial: +.. _serial5: **serial** @@ -272,8 +272,10 @@ number of serial refinements - Optional -.. _filename: +.. _filename5: **filename** mesh filename + + - Optional From 9fc2515e6ad68a79246905f14d3b1720a57c15f1 Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Tue, 27 Apr 2021 10:14:26 -0500 Subject: [PATCH 08/12] cleanup: docs adjustments per @white238 suggestions --- src/axom/inlet/SphinxWriter.hpp | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/axom/inlet/SphinxWriter.hpp b/src/axom/inlet/SphinxWriter.hpp index 3536239dd0..d89d2202e8 100644 --- a/src/axom/inlet/SphinxWriter.hpp +++ b/src/axom/inlet/SphinxWriter.hpp @@ -41,13 +41,13 @@ class SphinxWriter : public Writer public: /*! ******************************************************************************* - * \brief Supported phinx style options + * \brief Supported Sphinx style options ******************************************************************************* */ enum class Style { // FIXME: These names are not clear at all - Table, // Tables for the child Fields/Functions of each Container + Singular, // Tables for the child Fields/Functions of each Container Nested // Table of contents for each Container, then sections for each child }; @@ -62,7 +62,7 @@ class SphinxWriter : public Writer */ SphinxWriter(const std::string& fileName, const std::string& title = {}, - const Style style = Style::Table); + const Style style = Style::Singular); void documentContainer(const Container& container) override; @@ -169,6 +169,10 @@ class SphinxWriter : public Writer { std::string name; std::string description; + /** + * \brief Whether the container contains any fields/functions in any of its subcontainers + * \see detail::isTrivial + */ bool isTrivial; }; std::vector childContainers; From 7a0015d12b5168c2e4b3f4518c2e910865e92621 Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Tue, 27 Apr 2021 15:17:46 -0500 Subject: [PATCH 09/12] fix: copy-paste error with docs example --- .../mfem_coefficient_nested_documentation.rst | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/src/axom/inlet/docs/sphinx/mfem_coefficient_nested_documentation.rst b/src/axom/inlet/docs/sphinx/mfem_coefficient_nested_documentation.rst index bdd4753c6a..3d49afdcd6 100644 --- a/src/axom/inlet/docs/sphinx/mfem_coefficient_nested_documentation.rst +++ b/src/axom/inlet/docs/sphinx/mfem_coefficient_nested_documentation.rst @@ -4,6 +4,7 @@ ===================================== MFEM Coefficient Output (nested mode) ===================================== + .. list-table:: :widths: 25 50 :header-rows: 1 @@ -12,7 +13,7 @@ MFEM Coefficient Output (nested mode) * - Name - Description * - `bcs`_ - - List of boundary conditions + - @@ -27,8 +28,6 @@ bcs Collection contents: -------------------- -List of boundary conditions - List of boundary conditions @@ -41,14 +40,14 @@ List of boundary conditions * - Name - Description * - `attrs`_ - - List of boundary attributes - * - `coef`_ + - + * - :ref:`coef` - The function representing the BC coefficient - * - `vec_coef`_ + * - :ref:`vec_coef` - The function representing the BC coefficient -.. _coef: +.. _coef3: **coef** @@ -58,7 +57,7 @@ The function representing the BC coefficient - Optional -.. _vec_coef: +.. _vec_coef3: **vec_coef** @@ -79,5 +78,3 @@ attrs -------------------- Collection contents: -------------------- - -List of boundary attributes From 4eb53eea9c7ccf85190ea8287009ac2dc5c8d164 Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Mon, 3 May 2021 17:11:52 -0500 Subject: [PATCH 10/12] rename: singular -> flat --- src/axom/inlet/SphinxWriter.hpp | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/axom/inlet/SphinxWriter.hpp b/src/axom/inlet/SphinxWriter.hpp index d89d2202e8..ecda19d635 100644 --- a/src/axom/inlet/SphinxWriter.hpp +++ b/src/axom/inlet/SphinxWriter.hpp @@ -46,8 +46,7 @@ class SphinxWriter : public Writer */ enum class Style { - // FIXME: These names are not clear at all - Singular, // Tables for the child Fields/Functions of each Container + Flat, // Tables for the child Fields/Functions of each Container Nested // Table of contents for each Container, then sections for each child }; @@ -62,7 +61,7 @@ class SphinxWriter : public Writer */ SphinxWriter(const std::string& fileName, const std::string& title = {}, - const Style style = Style::Singular); + const Style style = Style::Flat); void documentContainer(const Container& container) override; From 844bb2b1676e764ed6f7b70dae434bcbe45be254 Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Wed, 5 May 2021 08:45:45 -0500 Subject: [PATCH 11/12] cleanup: table -> nested in filenames --- ..._documentation.rst => example1_flat_documentation.rst} | 2 +- ...tation.rst => mfem_coefficient_flat_documentation.rst} | 2 +- ...entation.rst => nested_structs_flat_documentation.rst} | 2 +- src/axom/inlet/docs/sphinx/writers.rst | 8 ++++---- 4 files changed, 7 insertions(+), 7 deletions(-) rename src/axom/inlet/docs/sphinx/{example1_table_documentation.rst => example1_flat_documentation.rst} (93%) rename src/axom/inlet/docs/sphinx/{mfem_coefficient_table_documentation.rst => mfem_coefficient_flat_documentation.rst} (96%) rename src/axom/inlet/docs/sphinx/{nested_structs_table_documentation.rst => nested_structs_flat_documentation.rst} (98%) diff --git a/src/axom/inlet/docs/sphinx/example1_table_documentation.rst b/src/axom/inlet/docs/sphinx/example1_flat_documentation.rst similarity index 93% rename from src/axom/inlet/docs/sphinx/example1_table_documentation.rst rename to src/axom/inlet/docs/sphinx/example1_flat_documentation.rst index 216caaf252..b1a2f0ce77 100644 --- a/src/axom/inlet/docs/sphinx/example1_table_documentation.rst +++ b/src/axom/inlet/docs/sphinx/example1_flat_documentation.rst @@ -2,7 +2,7 @@ .. |check| unicode:: U+2611 .. CHECKED BOX =============================================== -Example Output: Input File Options (table mode) +Example Output: Input File Options (flat mode) =============================================== -------------- diff --git a/src/axom/inlet/docs/sphinx/mfem_coefficient_table_documentation.rst b/src/axom/inlet/docs/sphinx/mfem_coefficient_flat_documentation.rst similarity index 96% rename from src/axom/inlet/docs/sphinx/mfem_coefficient_table_documentation.rst rename to src/axom/inlet/docs/sphinx/mfem_coefficient_flat_documentation.rst index eaf47e4aa8..ee099f05c8 100644 --- a/src/axom/inlet/docs/sphinx/mfem_coefficient_table_documentation.rst +++ b/src/axom/inlet/docs/sphinx/mfem_coefficient_flat_documentation.rst @@ -2,7 +2,7 @@ .. |check| unicode:: U+2611 .. CHECKED BOX ==================================== -MFEM Coefficient Output (table mode) +MFEM Coefficient Output (flat mode) ==================================== --- diff --git a/src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst b/src/axom/inlet/docs/sphinx/nested_structs_flat_documentation.rst similarity index 98% rename from src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst rename to src/axom/inlet/docs/sphinx/nested_structs_flat_documentation.rst index f1d0085ba0..a48cb5dafa 100644 --- a/src/axom/inlet/docs/sphinx/nested_structs_table_documentation.rst +++ b/src/axom/inlet/docs/sphinx/nested_structs_flat_documentation.rst @@ -2,7 +2,7 @@ .. |check| unicode:: U+2611 .. CHECKED BOX ================================== -Nested Structs Output (table mode) +Nested Structs Output (flat mode) ================================== ------ diff --git a/src/axom/inlet/docs/sphinx/writers.rst b/src/axom/inlet/docs/sphinx/writers.rst index 7d96705ac6..dd04cb4a9b 100644 --- a/src/axom/inlet/docs/sphinx/writers.rst +++ b/src/axom/inlet/docs/sphinx/writers.rst @@ -23,7 +23,7 @@ compatible with the `Sphinx `_ documentat The ``SphinxWriter`` currently has two styles available: -- A table-based style that, for each ``Container``, generates a table for its child fields and functions +- A flat style that, for each ``Container``, generates a table for its child fields and functions - A nested style that includes a "table of contents" for each ``Container`` with links to full descriptions of child fields and functions @@ -32,7 +32,7 @@ For comparison, the following is produced from the ``documentation_generation.cp .. toctree:: :maxdepth: 1 - example1_table_documentation + example1_flat_documentation example1_nested_documentation ...from the ``mfem_coefficient.cpp`` example: @@ -40,7 +40,7 @@ For comparison, the following is produced from the ``documentation_generation.cp .. toctree:: :maxdepth: 1 - mfem_coefficient_table_documentation + mfem_coefficient_flat_documentation mfem_coefficient_nested_documentation ...and from the ``nested_structs.cpp`` example: @@ -48,7 +48,7 @@ For comparison, the following is produced from the ``documentation_generation.cp .. toctree:: :maxdepth: 1 - nested_structs_table_documentation + nested_structs_flat_documentation nested_structs_nested_documentation ----------- From 8834021be87f50e0e9e67fb6ddce2eb9fc682b1c Mon Sep 17 00:00:00 2001 From: Josh Essman Date: Wed, 5 May 2021 08:46:19 -0500 Subject: [PATCH 12/12] docs: disable sphinx numfig option, refactor mint docs accordingly --- .../docs/sphinx/sections/architecture.rst | 12 ++--- .../docs/sphinx/sections/execution_model.rst | 6 +-- .../docs/sphinx/sections/getting_started.rst | 8 +-- .../sphinx/sections/mesh_representation.rst | 39 +++++++------- .../mint/docs/sphinx/sections/mesh_types.rst | 52 +++++++++---------- .../sphinx/sections/preliminary_concepts.rst | 8 +-- .../mint/docs/sphinx/sections/tutorial.rst | 24 ++++----- .../docs/sphinx/sections/architecture.rst | 7 +-- src/conf.py | 3 +- 9 files changed, 78 insertions(+), 81 deletions(-) diff --git a/src/axom/mint/docs/sphinx/sections/architecture.rst b/src/axom/mint/docs/sphinx/sections/architecture.rst index c8c5792248..62fbe940e2 100644 --- a/src/axom/mint/docs/sphinx/sections/architecture.rst +++ b/src/axom/mint/docs/sphinx/sections/architecture.rst @@ -19,9 +19,9 @@ The :ref:`Architecture` of Mint's *mesh data model* consists of a class hierarchy that follows directly the taxonomy of :ref:`MeshTypes` discussed earlier. The constituent classes of the *mesh data model* are combined using a mix of class *inheritance* and *composition*, as illustrated in -the class diagram depicted in :numref:`figs/classDiagram`. +the :ref:`class diagram `. -.. _figs/classDiagram: +.. _figs-classDiagram: .. figure:: ../figures/class_diagram.png :align: center :scale: 50% @@ -61,11 +61,11 @@ Notably, the computational domain can consist of one or more blocks, which are usually defined by the user or application. Each block is then subsequently partitioned to multiple domains that are distributed across processing units for parallel computation. For example, a sample block and domain decomposition -is depicted in :numref:`figs/decomp`. Each of the constituent domains is +is depicted in :ref:`the following figure `. Each of the constituent domains is represented by a corresponding ``mint::Mesh`` instance, which in aggregate define the entire problem domain. -.. _figs/decomp: +.. _figs-decomp: .. figure:: ../figures/decomp.png :align: center :scale: 35% @@ -152,9 +152,9 @@ Concrete Mesh Classes The :ref:`ConcreteMeshClasses`, extend :ref:`TheMeshBaseClass` and implement the underlying :ref:`MeshRepresentation` of the various :ref:`MeshTypes`, -depicted in :numref:`figs/meshtypes`. +depicted in :ref:`the following figure `. -.. _figs/meshtypes: +.. _figs-meshtypes: .. figure:: ../figures/meshtypes.png :align: center :scale: 35% diff --git a/src/axom/mint/docs/sphinx/sections/execution_model.rst b/src/axom/mint/docs/sphinx/sections/execution_model.rst index 06efd2d884..600d8cc5a1 100644 --- a/src/axom/mint/docs/sphinx/sections/execution_model.rst +++ b/src/axom/mint/docs/sphinx/sections/execution_model.rst @@ -40,9 +40,9 @@ The :ref:`sections/execution_model` provides :ref:`NodeTraversalFunctions`, :ref:`CellTraversalFunctions` and :ref:`FaceTraversalFunctions` to iterate and operate on the constituent :ref:`Nodes`, :ref:`Cells` and :ref:`Faces` of the mesh respectively. The general form of these functions is shown -in :numref:`figs/execModel`. +in :ref:`the execution model diagram `. -.. _figs/execModel: +.. _figs-execModel: .. figure:: ../figures/execmodel.png :align: center :scale: 50% @@ -51,7 +51,7 @@ in :numref:`figs/execModel`. General form of the constituent templated functions of the :ref:`sections/execution_model` -As shown in :numref:`figs/execModel`, the key elements of the functions +As shown in :ref:`the execution model diagram `, the key elements of the functions that comprise the :ref:`sections/execution_model` are: * **The Iteration Space:** Indicated by the function suffix, used to diff --git a/src/axom/mint/docs/sphinx/sections/getting_started.rst b/src/axom/mint/docs/sphinx/sections/getting_started.rst index 179a69f7db..284b93b610 100644 --- a/src/axom/mint/docs/sphinx/sections/getting_started.rst +++ b/src/axom/mint/docs/sphinx/sections/getting_started.rst @@ -327,9 +327,9 @@ defined on the interval :math:`\mathcal{I}:[-5.0,5.0] \times [-5.0,5.0]`. The resulting VTK file is stored in the specified file, ``uniform_mesh.vtk``. A depiction of the mesh showing a plot of `Himmelblau's Function`_ computed over the constituent :ref:`Nodes` of the mesh is illustrated in -:numref:`figs/intro_mesh`. +:ref:`the following plot `. -.. _figs/intro_mesh: +.. _figs-intro_mesh: .. figure:: ../figures/intro_mesh.png :align: center :alt: Resulting Uniform mesh @@ -348,9 +348,9 @@ the ``--unstructured`` option at the command line as follows: The code will generate an :ref:`UnstructuredMesh` by triangulating the :ref:`UniformMesh` such that each quadrilateral is subdivided into four triangles. The resulting unstructured mesh is stored in a VTK file, ``unstructured_mesh.vtk``, -depicted in :numref:`figs/intro_mesh_unstructured`. +depicted in :ref:`the following plot `. -.. _figs/intro_mesh_unstructured: +.. _figs-intro_mesh_unstructured: .. figure:: ../figures/intro_mesh_unstructured.png :align: center :alt: Resulting Unstructured mesh diff --git a/src/axom/mint/docs/sphinx/sections/mesh_representation.rst b/src/axom/mint/docs/sphinx/sections/mesh_representation.rst index 005828e346..7289775f92 100644 --- a/src/axom/mint/docs/sphinx/sections/mesh_representation.rst +++ b/src/axom/mint/docs/sphinx/sections/mesh_representation.rst @@ -44,10 +44,10 @@ defined by the collection of topological entities, e.g. the :ref:`Cells`, broadly referred to as :ref:`Connectivity` information. Each topological entity in the mesh is identified by a unique index, as depicted in the sample :ref:`UnstructuredMesh` shown in -:numref:`figs/meshRepresentation`. This provides a convenient way to traverse +:ref:`the following mesh `. This provides a convenient way to traverse and refer to individual entities in the mesh. -.. _figs/meshRepresentation: +.. _figs-meshRepresentation: .. figure:: ../figures/mesh_representation.png :align: center :scale: 95% @@ -74,7 +74,8 @@ A cell, :math:`\mathcal{C}_i`, is given by an ordered list of :ref:`Nodes`, :math:`n_j \in \mathcal{C}_i`, corresponds to a unique node index in the mesh. The order of :ref:`Nodes` defining a cell is determined according to a prescribed local numbering convention for a -particular cell type. See :numref:`figs/linearCells` and :numref:`figs/q2Cells`. +particular cell type. See the supported :ref:`linear cell types ` +and :ref:`quadratic cell types `. All Mint :ref:`CellTypes` follow the `CGNS Numbering Conventions`_. .. _Faces: @@ -85,7 +86,7 @@ Faces Similarly, a face, :math:`\mathcal{F}_i`, is defined by an ordered list of :ref:`Nodes`, :math:`\mathcal{F}_i=\{n_0,n_1,...,n_k\}`. Faces are essentially :ref:`Cells` whose topological dimension is one less than the dimension of the -:ref:`Cells` they are bound to. See :numref:`figs/cellFaces`. +:ref:`Cells` they are bound to. See the :ref:`cell faces diagram `. Consequently, the constituent faces of a 3D cell are 2D topological entities, such as *triangles* or *quads*, depending on the cell type. The faces of a 2D cell are 1D topological entities, i.e. *segments*. Last, the faces of a 1D cell @@ -97,7 +98,7 @@ are 0D topological entities, i.e. :ref:`Nodes`. mesh :ref:`Nodes`, hence, Mint does not explicitly support :ref:`Faces` in 1D. -.. _figs/cellFaces: +.. _figs-cellFaces: .. figure:: ../figures/cell_faces.png :align: center :alt: Cell Faces @@ -128,9 +129,9 @@ are 0D topological entities, i.e. :ref:`Nodes`. As with :ref:`Cells`, the ordering of the constituent nodes of a face is determined by the cell type. However, by convention, the orientation of a face is according to an outward pointing face normal, as illustrated in - :numref:`figs/faceOrientation`. + the :ref:`face orientation diagram `. - .. _figs/faceOrientation: + .. _figs-faceOrientation: .. figure:: ../figures/face_orientation.png :align: center :alt: Face Orientation @@ -144,7 +145,8 @@ are 0D topological entities, i.e. :ref:`Nodes`. From the viewpoint of a cell, :math:`\mathcal{C}_k`, its constituent faces, defined in the local node numbering of the cell, are oriented according to an outward facing normal with respect to the cell, - :math:`\mathcal{C}_k`. For example, in :numref:`figs/faceOrientation` (a), + :math:`\mathcal{C}_k`. + For example, in the :ref:`face orientation diagram ` (a), the triangle, :math:`\mathcal{C}_k`, has three faces that are oriented according to an outward facing normal and defined using local node numbers with respect to their cell as follows, :math:`\mathcal{F}_0=\{0,1\}`, @@ -154,8 +156,9 @@ are 0D topological entities, i.e. :ref:`Nodes`. denoted by :math:`\mathcal{C}_0` and :math:`\mathcal{C}_1`. By convention, from the viewpoint of a face, :math:`\mathcal{F}_k`, defined using global node numbers, the face is oriented according to an outward facing normal with - respect to the cell corresponding to :math:`\mathcal{C}_0`. As depicted in - :numref:`figs/faceOrientation` (b), the face denoted by :math:`\mathcal{F}_k` + respect to the cell corresponding to :math:`\mathcal{C}_0`. As depicted in the + :ref:`face orientation diagram ` (b), + the face denoted by :math:`\mathcal{F}_k` has an outward facing normal with respect to :math:`\mathcal{C}_0`, consequently it is defined as follows, :math:`\mathcal{F}_k=\{1,2\}`. @@ -198,9 +201,9 @@ Depending on the numerical scheme employed and the :ref:`CellTypes` used, additional mesh :ref:`Nodes` may be located on the constituent cell faces, edges and in the cell interior. For example, in the Finite Element Method (FEM), the nodes for the linear -Lagrange Finite Elements, see :numref:`figs/linearCells`, are located at the -cell *vertices*. However, for quadratic :ref:`CellTypes`, -see :numref:`figs/q2cells`, the *Lagrange* :math:`P^2` finite element, +Lagrange Finite Elements, see :ref:`the supported linear cell types `, +are located at the cell *vertices*. However, for quadratic :ref:`CellTypes`, +see :ref:`the quadratic cell types list `, the *Lagrange* :math:`P^2` finite element, for the quadrilateral and hexahedron (in 3D) cells, includes as :ref:`Nodes`, the cell, face and edge (in 3D) centroids in addition to the cell *vertices*. Other higher order finite elements may involve additional nodes for each edge @@ -213,13 +216,14 @@ Connectivity The topological connections or *adjecencies* between the :ref:`Cells`, :ref:`Faces` and :ref:`Nodes` comprising the mesh, give rise to a hierarchical -topological structure, depicted in :numref:`figs/topological_structure`, that is +topological structure, depicted in the +:ref:`topological structure diagram `, that is broadly referred to as :ref:`Connectivity` information. At the top level, a mesh consists of one or more :ref:`Cells`, which constitute the highest dimensional entity comprising the mesh. Each cell is bounded by zero or more :ref:`Faces`, each of which is bounded by one or more :ref:`Nodes`. -.. _figs/topological_structure: +.. _figs-topological_structure: .. figure:: ../figures/topological_structure.png :align: center :scale: 95% @@ -230,7 +234,7 @@ dimensional entity comprising the mesh. Each cell is bounded by zero or more The topological connections between the constituent entities of the mesh can be distinguished in (a) *downward* and (b) *upward* topological connections, as -illustrated in :numref:`figs/topological_structure`. +illustrated in the :ref:`topological structure diagram `. * The downward topological connections encode the connections from higher dimensional mesh entities to lower dimensional entities, @@ -325,6 +329,3 @@ application may need. .. ############################################################################# .. include:: citations.rst - - - diff --git a/src/axom/mint/docs/sphinx/sections/mesh_types.rst b/src/axom/mint/docs/sphinx/sections/mesh_types.rst index 78dd8029a3..4203c87d6b 100644 --- a/src/axom/mint/docs/sphinx/sections/mesh_types.rst +++ b/src/axom/mint/docs/sphinx/sections/mesh_types.rst @@ -154,7 +154,7 @@ the following sections. Curvilinear Mesh """"""""""""""""" -The :ref:`CurvilinearMesh`, shown in :numref:`figs/curvilinearMeshExample`, is +The :ref:`CurvilinearMesh`, shown in the :ref:`following figure `, is logically a *regular* mesh, however in contrast to the :ref:`RectilinearMesh` and :ref:`UniformMesh`, the :ref:`Nodes` of a :ref:`CurvilinearMesh` are not placed along the *Cartesian* grid lines. Instead, the equations of the governing @@ -163,7 +163,7 @@ called a *curvilinear coordinate system*. Consequently, the :ref:`Topology` of a :ref:`CurvilinearMesh` is *implicit*, however its :ref:`Geometry`, given by the constituent :ref:`Nodes` of the mesh, is *explicit*. -.. _figs/curvilinearMeshExample: +.. _figs-curvilinearMeshExample: .. figure:: ../figures/structured_curvilinear_mesh.png :align: center :scale: 55% @@ -186,7 +186,7 @@ See the :ref:`sections/tutorial` for an example that demonstrates how to Rectilinear Mesh """"""""""""""""" -A :ref:`RectilinearMesh`, depicted in :numref:`figs/rectilinearMeshExample`, +A :ref:`RectilinearMesh`, depicted in :ref:`following figure `, divides the computational domain into a set of rectangular :ref:`Cells`, arranged on a *regular lattice*. However, in contrast to the :ref:`CurvilinearMesh`, the :ref:`Geometry` of the mesh is not mapped to a @@ -195,7 +195,7 @@ comprising a :ref:`RectilinearMesh` are parallel to the axis of the *Cartesian* coordinate system. Due to this restriction, the geometric domain and resulting mesh are always rectangular. -.. _figs/rectilinearMeshExample: +.. _figs-rectilinearMeshExample: .. figure:: ../figures/structured_rectilinear_mesh.png :align: center :scale: 35% @@ -224,7 +224,7 @@ See the :ref:`sections/tutorial` for an example that demonstrates how to Uniform Mesh """"""""""""" -A :ref:`UniformMesh`, depicted in :numref:`figs/uniformMeshExample`, is the +A :ref:`UniformMesh`, depicted in :ref:`following figure `, is the simplest of all three :ref:`StructuredMesh` types, but also, relatively the most restrictive of all :ref:`MeshTypes`. As with the :ref:`RectilinearMesh`, a :ref:`UniformMesh` divides the computational domain into a set of rectangular @@ -233,7 +233,7 @@ imposes the additional restriction that :ref:`Nodes` are uniformly distributed parallel to each axis. Therefore, in contrast to the :ref:`RectilinearMesh`, the spacing between adjacent :ref:`Nodes` in a :ref:`UniformMesh` is constant. -.. _figs/uniformMeshExample: +.. _figs-uniformMeshExample: .. figure:: ../figures/structured_uniform_mesh.png :align: center :scale: 35% @@ -335,11 +335,12 @@ impose any ordering constraints. Moreover, the :ref:`Cells` can also be depends on the application, the physics being modeled, and the numerical scheme employed. An example tetrahedral :ref:`UnstructuredMesh` of the F-17 blended wing fuselage configuration is shown in -:numref:`figs/UnstructuredMeshSingleShape`. For this type of complex geometries +:ref:`this sample unstructured mesh `. +For this type of complex geometries it is nearly impossible to obtain a :ref:`StructuredMesh` that is adequate for computation. -.. _figs/unstructuredMeshSingleShape: +.. _figs-unstructuredMeshSingleShape: .. figure:: ../figures/f17.png :align: center :scale: 35% @@ -360,7 +361,7 @@ equivalent to a 2D row-major array layout where the number of rows corresponds to the number of :ref:`Cells` in the mesh and the number of columns corresponds to the *stride*, i.e. the number of :ref:`Nodes` per cell. -.. _figs/singleCellTypeRep: +.. _figs-singleCellTypeRep: .. figure:: ../figures/SingleCellTypeMesh.png :align: center :alt: Mesh Representation of the Unstructured Mesh with Single Cell Topology @@ -372,7 +373,7 @@ to the *stride*, i.e. the number of :ref:`Nodes` per cell. constituent :ref:`Nodes` of each triangle. This simple concept is best illustrated with an example. -:numref:`figs/singleCellTypeRep` depicts a sample :ref:`UnstructuredMesh` with +The :ref:`above figure ` depicts a sample :ref:`UnstructuredMesh` with :ref:`SingleCellTopology` consisting of :math:`N_c=4` triangular :ref:`Cells`. Each triangular cell, :math:`C_i`, is defined by :math:`||C_i||` :ref:`Nodes`. In this case, :math:`||C_i||=3`. @@ -387,8 +388,8 @@ In this case, :math:`||C_i||=3`. Consequently, the length of the cell-to-node :ref:`Connectivity` array is then given by :math:`N_c \times ||C_i||`. The node indices for each of the cells are stored from left to right. The base offset for a given cell is given -as a multiple of the cell index and the *stride*. As illustrated in -:numref:`figs/singleCellTypeRep`, the base offset for cell :math:`C_0` is +as a multiple of the cell index and the *stride*. As illustrated in the +:ref:`above figure `, the base offset for cell :math:`C_0` is :math:`0 \times 3 = 0`, the offest for cell :math:`C_1` is :math:`1 \times 3 = 3`, the offset for cell :math:`C_2` is :math:`2 \times 3 = 6` and so on. @@ -461,11 +462,11 @@ cell type is said to be *mixed*. an :ref:`UnstructuredMesh` with :ref:`MixedCellTopology` is sometimes also called a *mixed cell mesh* or *hybrid mesh*. -.. _figs/unstructuredMeshMixedShape: +.. _figs-unstructuredMeshMixedShape: .. figure:: ../figures/unstructured_mixed_mesh.png :align: center :scale: 95% - :alt: Sample Unstrucrured Mesh (mixed shape topology) + :alt: Sample Unstructured Mesh (mixed shape topology) Sample :ref:`UnstructuredMesh` with :ref:`MixedCellTopology` of a Generic wing/fuselage configuration. The mesh consists of high-aspect ratio prism @@ -489,8 +490,8 @@ boundary layer normal to the wall. Typically, high-aspect ratio, anisotropic viscous region of the computational domain, while isotropic *tetrahedron* or *hexahedron* :ref:`Cells` are used in the *inviscid* region to solve the Euler equations. The sample :ref:`MixedCellTopology` :ref:`UnstructuredMesh`, of a -Generic Wing/Fuselage configuration, depicted in -:numref:`figs/unstructuredMeshMixedShape`, consists of *triangular prism* +Generic Wing/Fuselage configuration, depicted in the above +:ref:`unstructured mesh `, consists of *triangular prism* :ref:`Cells` for the *viscous* boundary layer portion of the domain that are stitched to *tetrahedra* :ref:`Cells` for the inviscid/Euler portion of the mesh. @@ -506,7 +507,7 @@ the :ref:`SingleCellTopology` :ref:`MeshRepresentation`, cannot be employed to obtain cell-to-node information. For a :ref:`MixedCellTopology` an *indirect addressing* access scheme must be used instead. -.. _figs/mixedCellTypeRep: +.. _figs-mixedCellTypeRep: .. figure:: ../figures/MixedCellTypeMesh.png :align: center :alt: Mesh Representation of the Unstructured Mesh with Mixed Cell Topology @@ -527,7 +528,7 @@ There are a number of ways to represent a :ref:`MixedCellTopology` mesh. In addition to the cell-to-node :ref:`Connectivity` array, Mint's :ref:`MeshRepresentation` for a :ref:`MixedCellTopology` :ref:`UnstructuredMesh` employs two additional arrays. See sample mesh and corresponding -:ref:`MeshRepresentation` in :numref:`figs/mixedCellTypeRep`. +:ref:`MeshRepresentation` in the :ref:`above figure `. First, the *Cell Offsets* array is used to provide indirect addressing to the cell-to-node information of each constituent mesh cell. Second, the :ref:`CellTypes` array is used to store the cell type of each cell in the @@ -603,10 +604,10 @@ Cell Types """"""""""" Mint currently supports the common Linear :ref:`CellTypes`, -depicted in :numref:`figs/linearCells`, as well as, support for -quadratic, quadrilateral and hexahedron :ref:`Cells`, see :numref:`figs/q2Cells`. +depicted in :ref:`the linear cell types list `, as well as, support for +quadratic, quadrilateral and hexahedron :ref:`Cells`, see :ref:`the quadratic cell types `. -.. _figs/linearCells: +.. _figs-linearCells: .. figure:: ../figures/linear_cell_types.png :align: center :scale: 95% @@ -615,7 +616,7 @@ quadratic, quadrilateral and hexahedron :ref:`Cells`, see :numref:`figs/q2Cells` List of supported linear cell types and their respective local node numbering. -.. _figs/q2Cells: +.. _figs-q2Cells: .. figure:: ../figures/q2_cell_types.png :align: center :scale: 95% @@ -664,7 +665,7 @@ Add a New Cell Type Particle Mesh ^^^^^^^^^^^^^^ -A :ref:`ParticleMesh`, depicted in :numref:`figs/particleMesh`, discretizes the +A :ref:`ParticleMesh`, depicted in the :ref:`following figure `, discretizes the computational domain by a set of *particles* which correspond to the :ref:`Nodes` at which the solution is evaluated. A :ref:`ParticleMesh` is commonly employed in the so called *particle* methods, such as *Smoothed Particle Hydrodynamics* @@ -681,7 +682,7 @@ a :ref:`ParticleMesh` does not have :ref:`Faces` and any associated employ a :ref:`ParticleMesh` discretization are often referred to as *meshless* or *mesh-free* methods. -.. _figs/particleMesh: +.. _figs-particleMesh: .. figure:: ../figures/particles.png :align: center :scale: 35% @@ -710,6 +711,3 @@ be stored explicitly. .. ############################################################################# .. include:: citations.rst - - - diff --git a/src/axom/mint/docs/sphinx/sections/preliminary_concepts.rst b/src/axom/mint/docs/sphinx/sections/preliminary_concepts.rst index 334c98fd85..5c1318fdb7 100644 --- a/src/axom/mint/docs/sphinx/sections/preliminary_concepts.rst +++ b/src/axom/mint/docs/sphinx/sections/preliminary_concepts.rst @@ -24,7 +24,7 @@ done numerically, which requires discretizing the governing PDE by a numerical scheme, such as a Finite Difference (FD), Finite Volume (FV), or, the Finite Element Method (FEM), chief among them. -.. _figs/meshedDomain: +.. _figs-meshedDomain: .. figure:: ../figures/meshed_domain.png :align: center :scale: 100% @@ -37,12 +37,12 @@ Finite Element Method (FEM), chief among them. governing PDE are stored and evaluated. Discretization of the governing PDE requires the domain to be approximated -with a mesh. For example, :numref:`figs/meshedDomain` (a) depicts a geometric +with a mesh. For example, the :ref:`above figure ` (a) depicts a geometric domain, :math:`\Omega`. The corresponding mesh, :math:`\mathcal{M}(\Omega)`, -is illustrated in :numref:`figs/meshedDomain` (b). The mesh approximates +is illustrated in :ref:`above figure ` (b). The mesh approximates the geometric domain, :math:`\Omega`, by a finite number of simple geometric entities, such as *nodes* and *cells*, depicted in red in -:numref:`figs/meshedDomain` (b). These geometric entities comprising the mesh +:ref:`above figure ` (b). These geometric entities comprising the mesh define the discrete locations, in space and time, at which the unknown variables, i.e., the *degrees of freedom* of the governing PDE, are evaluated, by the numerical scheme being employed. diff --git a/src/axom/mint/docs/sphinx/sections/tutorial.rst b/src/axom/mint/docs/sphinx/sections/tutorial.rst index 5416c186a4..70c6029e80 100644 --- a/src/axom/mint/docs/sphinx/sections/tutorial.rst +++ b/src/axom/mint/docs/sphinx/sections/tutorial.rst @@ -44,9 +44,9 @@ can be easily constructed as follows: :language: C++ :linenos: -The resulting mesh is depicted in :numref:`figs/uniformMesh50x50`. +The resulting mesh is depicted in the :ref:`following figure `. -.. _figs/uniformMesh50x50: +.. _figs-uniformMesh50x50: .. figure:: ../figures/structured_uniform_mesh.png :align: center :scale: 35% @@ -72,7 +72,7 @@ The following code snippet illustrates how to construct a :math:`25 \times 25` :ref:`RectilinearMesh` where the spacing of the :ref:`Nodes` grows according to an exponential *stretching function* along the :math:`x` and :math:`y` axis respectively. The resulting mesh is depicted in -:numref:`figs/rectilinearMesh25x25`. +the :ref:`following figure `. .. literalinclude:: ../../../examples/user_guide/mint_tutorial.cpp :start-after: sphinx_tutorial_construct_rectilinear_start @@ -80,7 +80,7 @@ respectively. The resulting mesh is depicted in :language: C++ :linenos: -.. _figs/rectilinearMesh25x25: +.. _figs-rectilinearMesh25x25: .. figure:: ../figures/structured_rectilinear_mesh.png :align: center :scale: 35% @@ -106,7 +106,7 @@ separate arrays, :math:`x`, :math:`y`, and :math:`z`. The following code snippet illustrates how to construct a :math:`25 \times 25` :ref:`CurvilinearMesh`. The coordinates of the :ref:`Nodes` follow from the equation of a cylinder with a radius of :math:`2.5`. The resulting mesh is -depicted in :numref:`figs/curvilinearMesh25x25`. +depicted in the :ref:`following figure `. .. literalinclude:: ../../../examples/user_guide/mint_tutorial.cpp :start-after: sphinx_tutorial_construct_curvilinear_start @@ -114,7 +114,7 @@ depicted in :numref:`figs/curvilinearMesh25x25`. :language: C++ :linenos: -.. _figs/curvilinearMesh25x25: +.. _figs-curvilinearMesh25x25: .. figure:: ../figures/SampleMesh.png :align: center :scale: 35% @@ -140,7 +140,7 @@ Since both :ref:`Geometry` and :ref:`Topology` are explicit, an #. the :ref:`Cells` comprising the mesh, defined by the *cell-to-node* :ref:`Connectivity` -.. _figs/triangularMesh: +.. _figs-triangularMesh: .. figure:: ../figures/sample_unstructured_mesh.png :align: center :scale: 35% @@ -149,7 +149,7 @@ Since both :ref:`Geometry` and :ref:`Topology` are explicit, an Resulting :ref:`SingleCellTopology` :ref:`UnstructuredMesh` The following code snippet illustrates how to create the simple -:ref:`UnstructuredMesh` depicted in :numref:`figs/triangularMesh`. +:ref:`UnstructuredMesh` depicted in the :ref:`above figure `. .. literalinclude:: ../../../examples/user_guide/mint_tutorial.cpp :start-after: sphinx_tutorial_construct_unstructured_start @@ -164,7 +164,7 @@ class constructor correspond to the problem dimension and cell type, which in this case, is :math:`2` and ``mint::TRIANGLE`` respectively. Once the mesh is constructed, the :ref:`Nodes` and :ref:`Cells` are appended to the mesh by calls to the ``appendNode()`` and ``appendCell()`` methods respectively. -The resulting mesh is shown in :numref:`figs/triangularMesh`. +The resulting mesh is shown in the :ref:`above figure `. .. tip:: @@ -184,9 +184,9 @@ Compared to the :ref:`SingleCellTopology` :ref:`UnstructuredMesh`, a :ref:`MixedCellTopology` :ref:`UnstructuredMesh` has also explicit :ref:`Topology` and :ref:`Geometry`. However, the cell type is not fixed. Notably, the mesh can store different :ref:`CellTypes`, e.g. triangles and quads, -as shown in the simple 2D mesh depicted in :numref:`figs/mixedMesh`. +as shown in the simple 2D mesh depicted in the :ref:`following figure `. -.. _figs/mixedMesh: +.. _figs-mixedMesh: .. figure:: ../figures/sample_unstructured_mesh_mixed.png :align: center :scale: 35% @@ -203,7 +203,7 @@ As with the :ref:`SingleCellTopology` :ref:`UnstructuredMesh`, a The following code snippet illustrates how to create the simple :ref:`MixedCellTopology` :ref:`UnstructuredMesh` depicted in -:numref:`figs/mixedMesh`, consisting of :math:`2` *triangles* and +the :ref:`above figure `, consisting of :math:`2` *triangles* and :math:`1` *quadrilateral* :ref:`Cells`. .. literalinclude:: ../../../examples/user_guide/mint_tutorial.cpp diff --git a/src/axom/slic/docs/sphinx/sections/architecture.rst b/src/axom/slic/docs/sphinx/sections/architecture.rst index 6e661e53f0..d4ae8bf626 100644 --- a/src/axom/slic/docs/sphinx/sections/architecture.rst +++ b/src/axom/slic/docs/sphinx/sections/architecture.rst @@ -10,7 +10,7 @@ Component Architecture Slic provides a simple and easy to use logging interface for applications. -.. _figs/slic_architecture: +.. _figs-slic_architecture: .. figure:: ../figures/architecture.png :align: center @@ -20,7 +20,7 @@ Slic provides a simple and easy to use logging interface for applications. Basic Component Architecture of Slic. The basic component architecture of Slic, depicted in -:numref:`figs/slic_architecture`, consists of three main components: +:ref:`the above figure `, consists of three main components: #. A static logger API. This serves as the primary interface to the application. @@ -448,6 +448,3 @@ any of the :ref:`BuiltInLogStreams`, as demonstrated in the code snippet below: .. ############################################################################# .. include:: citations.rst - - - diff --git a/src/conf.py b/src/conf.py index afcaca01a8..63d4ffb065 100644 --- a/src/conf.py +++ b/src/conf.py @@ -90,7 +90,8 @@ # -- Option for numbering figures/tables/etc.----------------------------------- # Note: numfig requires Sphinx (1.3+) -numfig = True +# JBE: Option disabled to avoid potentially confusing table numbers in Inlet docs +numfig = False # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the