AppSyntax Extension

The AppSyntax Extension defines the !syntax markdown command, which contains various sub-commands for creating MOOSE specific links and tables within your markdown, each are explained below. Note, the examples below refer to documentation associated with Kernels and/or the Diffusion Kernel. This should be replaced by the syntax for the system or object being documented. The configuration options for the extension itself are listed in Table 1.

Table 1: Configuration options for the AppSyntax extension.

Key	Default	Description
active	True	Toggle for disabling the extension. This only changes the initial active state, use setActive to control at runtime.
executable	None	The MOOSE application executable to use for generating syntax.
app_name	None	The MOOSE application name (e.g., moose_test); if not provided an attempt will be made to determine the name.
sources	[]	List of source directories to investigate for class information.
includes	[]	List of include directories to investigate for class information.
inputs	[]	List of directories to interrogate for input files using an object.
allow-test-objects	False	Enable documentation for test objects.
hide	None	DEPRECATED
remove	None	List or Dictionary of lists of syntax to remove.
visible	['required', 'optional']	Parameter groups to show as un-collapsed.
alias	None	Dictionary of syntax aliases.
unregister	None	A `dict` or `dict` of `dict` including syntax to unregister (key='moose_base', value='parent_syntax')
markdown	None	A `dict` or `dict` of `dict` including markdown files to explicitly set a custom, additional markdown reference (key='syntax', value='file.md')
external_icon	feedback	Icon name for the alert title when unavailable syntax is located on an external page.
external_alert	warning	Alert name when unavailable syntax is located on an external page.

Class Description (`!syntax description`)

The description sub-command adds a paragraph with the content of InputParameters object class descriptions, which is added in the MOOSE application within the validParams method. The available settings are included in Table 2.

Table 2: Command settings for the !syntax description command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	The class settings to be passed to the rendered tag.
syntax	None	The name of the syntax to extract. If the name of the syntax is the first item in the settings the 'syntax=' may be omitted, e.g., `!syntax parameters /Kernels/Diffusion`.

For example, the FileMesh object includes a validParams function as shown in Listing 1. Notice, that the addClassDescription method includes a short description of the object. To display this text the !syntax description command is used followed by the MOOSE input file syntax for the object as in Example 1.

Example 1: Example use of the !syntax description command.

Markdown
HTML

!syntax description /Mesh/FileMesh style=color:green

Listing 1: The validParams function from the FileMesh object.

#include "FileMesh.h"
#include "Parser.h"
#include "MooseUtils.h"
#include "Moose.h"
#include "MooseApp.h"
#include "FileMeshGenerator.h"

#include "libmesh/exodusII_io.h"
#include "libmesh/mesh_tools.h"
#include "libmesh/nemesis_io.h"
#include "libmesh/parallel_mesh.h"

registerMooseObject("MooseApp", FileMesh);

InputParameters
FileMesh::validParams()
{
  InputParameters params = MooseMesh::validParams();
  params.addRequiredParam<MeshFileName>("file", "The name of the mesh file to read");
  params.addParam<bool>("clear_spline_nodes",
                        false,
                        "If clear_spline_nodes=true, IsoGeometric Analyis spline nodes "
                        "and constraints are removed from an IGA mesh, after which only "
                        "C^0 Rational-Bernstein-Bezier elements will remain.");
  params.addClassDescription("Read a mesh from a file.");
  return params;
}

Object Parameters (`!syntax parameters`)

The parameters sub-command provides a means for displaying the default input file syntax for an object as shown in Example 2. The available settings for the parameters command are shown in Table 3.

Table 3: Command settings for the !syntax parameters command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	The class settings to be passed to the rendered tag.
syntax	None	The name of the syntax to extract. If the name of the syntax is the first item in the settings the 'syntax=' may be omitted, e.g., `!syntax parameters /Kernels/Diffusion`.
heading	Input Parameters	The heading title for the input parameters table, use 'None' to remove the heading.
heading-level	2	Heading level for section title.
groups	None	Space separated list of groups, in desired order, to output.
hide	None	Space separated list of parameters to remove from output.
show	None	Space separated list of parameters to display in output.
visible	None	Space separated list of parameter groups to display with un-collapsed sections.

Example 2: Example use of the !syntax parameters command.

Markdown
HTML

!syntax parameters /Dampers/ConstantDamper

Input Files (`!syntax inputs`)

In many cases it is useful to know where in the examples, tutorials, or tests an object is utilized in an input file. Therefore, inputs sub-command is defined. Example 3 lists all the input files that use include the ConstantDamper object and Table 4 provides the available settings for the inputs command.

Table 4: Command settings for the !syntax inputs command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	The class settings to be passed to the rendered tag.
syntax	None	The name of the syntax to extract. If the name of the syntax is the first item in the settings the 'syntax=' may be omitted, e.g., `!syntax parameters /Kernels/Diffusion`.
heading	Input Files	Heading to include for sections, use 'None' to remove the title.
heading-level	2	Heading level for section title.

Example 3: Example use of the !syntax inputs command.

Markdown
HTML

!syntax inputs /Dampers/ConstantDamper

Child Objects (`!syntax children`)

MOOSE is designed on the idea of inheritance, as such it is often useful to understand which classes inherit from another. The children sub-command creates a list of all child classes of the given object, as shown in Example 4. The available settings for the children command are provided below.

Example 4: Example use of the !syntax children command.

Markdown
HTML

!syntax children /Kernels/Diffusion

Table 5: Command settings for the !syntax children command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	The class settings to be passed to the rendered tag.
syntax	None	The name of the syntax to extract. If the name of the syntax is the first item in the settings the 'syntax=' may be omitted, e.g., `!syntax parameters /Kernels/Diffusion`.
heading	Child Objects	Heading to include for sections, use 'None' to remove the title.
heading-level	2	Heading level for section title.

Actions, Objects, and Systems (`!syntax list`)

MOOSE is based on systems (e.g., Kernels), where each system contains a set of objects, actions, and subsystems that can be used within an input file block. It is desirable to list the available object for a given system, which is the reason behind the !syntax list command. The available settings for this command are included in Table 6.

Table 6: Command settings for the !syntax list command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	The class settings to be passed to the rendered tag.
syntax	None	The name of the syntax to extract. If the name of the syntax is the first item in the settings the 'syntax=' may be omitted, e.g., `!syntax parameters /Kernels/Diffusion`.
heading	AUTO	The heading title for the input parameters table, use 'None' to remove the heading.
heading-level	2	Heading level for section title.
group-headings	True	Display group headings.
groups	None	List of groups (apps) to include in the complete syntax list.
actions	True	Include a list of Action objects in syntax.
objects	True	Include a list of MooseObject objects in syntax.
subsystems	True	Include a list of sub system syntax in the output.

Example 5: Example use of the !syntax list command.

Markdown
HTML

!syntax list /Adaptivity

Complete Syntax List

!syntax complete level=3

(contrib/moose/framework/src/mesh/FileMesh.C)

// This file is part of the MOOSE framework
// https://www.mooseframework.org
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "FileMesh.h"
#include "Parser.h"
#include "MooseUtils.h"
#include "Moose.h"
#include "MooseApp.h"
#include "FileMeshGenerator.h"

#include "libmesh/exodusII_io.h"
#include "libmesh/mesh_tools.h"
#include "libmesh/nemesis_io.h"
#include "libmesh/parallel_mesh.h"

registerMooseObject("MooseApp", FileMesh);

InputParameters
FileMesh::validParams()
{
  InputParameters params = MooseMesh::validParams();
  params.addRequiredParam<MeshFileName>("file", "The name of the mesh file to read");
  params.addParam<bool>("clear_spline_nodes",
                        false,
                        "If clear_spline_nodes=true, IsoGeometric Analyis spline nodes "
                        "and constraints are removed from an IGA mesh, after which only "
                        "C^0 Rational-Bernstein-Bezier elements will remain.");
  params.addClassDescription("Read a mesh from a file.");
  return params;
}

FileMesh::FileMesh(const InputParameters & parameters)
  : MooseMesh(parameters),
    _file_name(getParam<MeshFileName>("file")),
    _dim(getParam<MooseEnum>("dim"))
{
}

FileMesh::FileMesh(const FileMesh & other_mesh)
  : MooseMesh(other_mesh), _file_name(other_mesh._file_name), _dim(other_mesh._dim)
{
}

FileMesh::~FileMesh() {}

std::unique_ptr<MooseMesh>
FileMesh::safeClone() const
{
  return _app.getFactory().copyConstruct(*this);
}

void
FileMesh::buildMesh()
{
  TIME_SECTION("buildMesh", 2, "Reading Mesh");

  getMesh().set_mesh_dimension(getParam<MooseEnum>("dim"));

  if (_is_nemesis)
  {
    // Nemesis_IO only takes a reference to DistributedMesh, so we can't be quite so short here.
    DistributedMesh & pmesh = cast_ref<DistributedMesh &>(getMesh());
    Nemesis_IO(pmesh).read(_file_name);

    getMesh().allow_renumbering(false);

    // Even if we want repartitioning when load balancing later, we'll
    // begin with the default partitioning defined by the Nemesis
    // file.
    bool skip_partitioning_later = getMesh().skip_partitioning();
    getMesh().skip_partitioning(true);
    getMesh().prepare_for_use();
    getMesh().skip_partitioning(skip_partitioning_later);
  }
  else // not reading Nemesis files
  {
    // See if the user has requested reading a solution from the file.  If so, we'll need to read
    // the mesh with the exodus reader instead of using mesh.read().  This will read the mesh on
    // every processor

    if (_app.getExodusFileRestart() && (_file_name.rfind(".exd") < _file_name.size() ||
                                        _file_name.rfind(".e") < _file_name.size()))
    {
      MooseUtils::checkFileReadable(_file_name);

      auto exreader = std::make_shared<ExodusII_IO>(getMesh());
      _app.setExReaderForRestart(std::move(exreader));
      exreader->read(_file_name);

      getMesh().allow_renumbering(false);
      getMesh().prepare_for_use();
    }
    else
    {
      _file_name = FileMeshGenerator::deduceCheckpointPath(*this, _file_name);

      // If we are reading a mesh while restarting, then we might have
      // a solution file that relies on that mesh partitioning and/or
      // numbering.  In that case, we need to turn off repartitioning
      // and renumbering, at least at first.
      bool restarting = _file_name.rfind(".cpa.gz") < _file_name.size();

      const bool skip_partitioning_later = restarting && getMesh().skip_partitioning();
      const bool allow_renumbering_later = restarting && getMesh().allow_renumbering();

      if (restarting)
      {
        getMesh().skip_partitioning(true);
        getMesh().allow_renumbering(false);
      }

      MooseUtils::checkFileReadable(_file_name);
      getMesh().read(_file_name);

      if (getParam<bool>("clear_spline_nodes"))
        MeshTools::clear_spline_nodes(getMesh());

      _app.possiblyLoadRestartableMetaData(MooseApp::MESH_META_DATA, _file_name);

      if (restarting)
      {
        getMesh().allow_renumbering(allow_renumbering_later);
        getMesh().skip_partitioning(skip_partitioning_later);
      }
    }
  }
}

void
FileMesh::read(const std::string & file_name)
{
  if (dynamic_cast<DistributedMesh *>(&getMesh()) && !_is_nemesis)
    getMesh().read(file_name, /*mesh_data=*/NULL, /*skip_renumber=*/false);
  else
    getMesh().read(file_name, /*mesh_data=*/NULL, /*skip_renumber=*/true);
}

Class Description ( ) !syntax description
Object Parameters ( ) !syntax parameters
Input Files ( ) !syntax inputs
Child Objects ( ) !syntax children
Actions , Objects , and Systems ( ) !syntax list
Complete Syntax List

AppSyntax Extension

Class Description (`!syntax description`)

Object Parameters (`!syntax parameters`)

Input Parameters

Required Parameters

Optional Parameters

Advanced Parameters

Input Files (`!syntax inputs`)

Child Objects (`!syntax children`)

Actions, Objects, and Systems (`!syntax list`)

Available Objects, Actions, and Subsystems

Complete Syntax List

AppSyntax Extension

Class Description (!syntax description)

Object Parameters (!syntax parameters)

Input Parameters

Required Parameters

Optional Parameters

Advanced Parameters

Input Files (!syntax inputs)

Child Objects (!syntax children)

Actions, Objects, and Systems (!syntax list)

Available Objects, Actions, and Subsystems

Complete Syntax List

(contrib/moose/framework/src/mesh/FileMesh.C)

Class Description (`!syntax description`)

Object Parameters (`!syntax parameters`)

Input Files (`!syntax inputs`)

Child Objects (`!syntax children`)

Actions, Objects, and Systems (`!syntax list`)