Listing Extension

The listing extension provides a mechanism for creating source code listings. The system allows for the inclusion of local content as well as complete or partial snippets of the desired source code and includes the ability to parse MOOSE input files and separate out blocks. The main purpose is to avoid copying code or input syntax into the documentation to avoid out-of-date content.

The extension provides the !listing command (see Command Extension), which allows for numbered captions to be applied, the Float Extension provides additional details. The following table list the available configure options for the extension.

KeyDefaultDescription
prefixListingThe caption prefix (e.g., Fig.).

The !listing command has the capability to include text from local content and arbitrary files (such as source code). files. There is a wide range of settings that are available to specialize how the code is imported. The complete list of available of settings are provided in Table 2 and the sections below provide various examples of using some of these settings.

Local Listing Content

It is possible to create a listing using local content. This is done by using the !listing command without any agruments with the desired content following the command, see Command Extension for details to how content is defined. The available settings for this command are given in Table 1.

Example 1: Example listing with content from local markdown.

{ "attributes": {}, "children": [], "name": "Code", "properties": { "code": "!listing id=local caption=A function for adding 42. language=cpp\ndouble add_forty_two(const double y);\ny += 42;\nreturn y;\n", "escape": true, "language": "text", "recursive": true, "string": null }, "type": "Code" }
!listing id=local caption=A function for adding 42. language=cpp
double add_forty_two(const double y);
y += 42;
return y;

Listing 1: A function for adding 42.

double add_forty_two(const double y);
y += 42;
return y;

Table 1: Settings available when creating a listing from local content.

KeyDefaultDescription
styleThe style settings that are passed to rendered HTML tag.
languageNoneThe language to use for highlighting, if not supplied it will be inferred from the extension (if possible).
idThe class settings to be passed to the rendered tag.
max-height350pxThe default height for listing content.
captionNoneThe caption to use for the listing content.
prefixNoneText to include prior to the included text.
classThe class settings to be passed to rendered HTML tag.

File Content

You can include complete files from the repository. For example, the following creates the code listing in Example 2.

Table 2: Settings available when capturing text from a file with the listing command.

KeyDefaultDescription
strip-headerTrueWhen True the MOOSE header is removed for display.
styleThe style settings that are passed to rendered HTML tag.
strip-extra-newlinesTrueRemoves extraneous new lines from the text.
indent0The level of indenting to apply to the included text.
languageNoneThe language to use for highlighting, if not supplied it will be inferred from the extension (if possible).
headerNoneText to include prior to the included text.
endNoneA portion of text that unique identifies the ending location for including text, if not provided the end of the file is used. By default this line is not included in the display.
footerText to include after to the included text.
re-flagsre.M|re.S|re.UPython re flags.
startNoneA portion of text that unique identifies the starting location for including text, if not provided the beginning of the file is utilized.
idThe class settings to be passed to the rendered tag.
max-height350pxThe default height for listing content.
captionNoneThe caption to use for the listing content.
prefixNoneText to include prior to the included text.
include-endFalseWhen True the texted captured by the 'end' setting is included in the displayed text.
linkTrueInclude a link to the filename after the listing.
reFalseExtract content via a regex, if the 'content' group exists it is used as the desired content, otherwise group 0 is used.
lineNoneA portion of text that unique identifies a single line to include.
strip-leading-whitespaceFalseWhen True leading white-space is removed from the included text.
classThe class settings to be passed to rendered HTML tag.
include-startTrueWhen False the texted captured by the 'start' setting is excluded in the displayed text.

Example 2: Example for showing a complete file.

{ "attributes": {}, "children": [], "name": "Code", "properties": { "code": "!listing framework/src/kernels/Diffusion.C\n", "escape": true, "language": "text", "recursive": true, "string": null }, "type": "Code" }
!listing framework/src/kernels/Diffusion.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 "Diffusion.h"

registerMooseObject("MooseApp", Diffusion);

template <>
InputParameters
validParams<Diffusion>()
{
  InputParameters params = validParams<Kernel>();
  params.addClassDescription("The Laplacian operator ($-\\nabla \\cdot \\nabla u$), with the weak "
                             "form of $(\\nabla \\phi_i, \\nabla u_h)$.");
  return params;
}

Diffusion::Diffusion(const InputParameters & parameters) : Kernel(parameters) {}

Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}

Real
Diffusion::computeQpJacobian()
{
  return _grad_phi[_j][_qp] * _grad_test[_i][_qp];
}
(framework/src/kernels/Diffusion.C)

Regular Expression Match

Regular expressions can be utilized to extract specific content from files. Example 3 uses a regular expression to extract the content of a class method.

Example 3: Example listing using the "re" setting.

{ "attributes": {}, "children": [], "name": "Code", "properties": { "code": "!listing framework/src/kernels/Diffusion.C\n re=Real\\sDiffusion::computeQpResidual.*?^}\n", "escape": true, "language": "text", "recursive": true, "string": null }, "type": "Code" }
!listing framework/src/kernels/Diffusion.C
         re=Real\sDiffusion::computeQpResidual.*?^}
Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}
(framework/src/kernels/Diffusion.C)

Single Line Match

It is possible to show a single line of a file by including a snippet that allows the line to be located within the file. If multiple matches occur only the first match will be shown. For example, the call to addClassDescription can be shown by adding the following.

Example 4: Example for displaying a single line from a file.

{ "attributes": {}, "children": [], "name": "Code", "properties": { "code": "!listing framework/src/kernels/Diffusion.C line=computeQp\n", "escape": true, "language": "text", "recursive": true, "string": null }, "type": "Code" }
!listing framework/src/kernels/Diffusion.C line=computeQp
Diffusion::computeQpJacobian()
(framework/src/kernels/Diffusion.C)

Range Line Match

Code starting and ending on lines containing a string is also possible by using the 'start' and 'end' options. If 'start' is omitted then the snippet will start at the beginning of the file. Similarly, if 'end' is omitted the snippet will include the remainder of the file content.

Example 5: Example listing using the "start" and "end" settings.

{ "attributes": {}, "children": [], "name": "Code", "properties": { "code": "!listing moose/test/tests/kernels/simple_diffusion/simple_diffusion.i\n start=Kernels\n end=Executioner\n", "escape": true, "language": "text", "recursive": true, "string": null }, "type": "Code" }
!listing moose/test/tests/kernels/simple_diffusion/simple_diffusion.i
         start=Kernels
         end=Executioner
[Kernels]
  [./diff]
    type = Diffusion
    variable = u
  [../]
[]

[BCs]
  [./left]
    type = DirichletBC
    variable = u
    boundary = left
    value = 0
  [../]
  [./right]
    type = DirichletBC
    variable = u
    boundary = right
    value = 1
  [../]
[]
(test/tests/kernels/simple_diffusion/simple_diffusion.i)

Input File Content

Like for C++ files, MOOSE input files also have additional capability, mainly the "block" setting (see Example 6 for a complete list). Including the block name the included content will be limited to the content matching the supplied name. Notice that the supplied name may be approximate; however, if it is not unique only the first match will appear.

Example 6: Example use of "block" setting for input files.

{ "attributes": {}, "children": [], "name": "Code", "properties": { "code": "!listing moose/test/tests/kernels/simple_diffusion/simple_diffusion.i\n block=Kernels\n id=input\n caption=Code listing of [MOOSE] input file block.\n", "escape": true, "language": "text", "recursive": true, "string": null }, "type": "Code" }
!listing moose/test/tests/kernels/simple_diffusion/simple_diffusion.i
         block=Kernels
         id=input
         caption=Code listing of [MOOSE] input file block.

Listing 2: Code listing of MOOSE input file block.


[Kernels]
  [./diff]
    type = Diffusion
    variable = u
  [../]
[]
(test/tests/kernels/simple_diffusion/simple_diffusion.i)
KeyDefaultDescription
strip-headerTrueWhen True the MOOSE header is removed for display.
strip-extra-newlinesTrueRemoves extraneous new lines from the text.
re-flagsre.M|re.S|re.UPython re flags.
strip-leading-whitespaceFalseWhen True leading white-space is removed from the included text.
max-height350pxThe default height for listing content.
headerNoneText to include prior to the included text.
prefixNoneText to include prior to the included text.
include-endFalseWhen True the texted captured by the 'end' setting is included in the displayed text.
idThe class settings to be passed to the rendered tag.
styleThe style settings that are passed to rendered HTML tag.
endNoneA portion of text that unique identifies the ending location for including text, if not provided the end of the file is used. By default this line is not included in the display.
reFalseExtract content via a regex, if the 'content' group exists it is used as the desired content, otherwise group 0 is used.
startNoneA portion of text that unique identifies the starting location for including text, if not provided the beginning of the file is utilized.
include-startTrueWhen False the texted captured by the 'start' setting is excluded in the displayed text.
linkTrueInclude a link to the filename after the listing.
lineNoneA portion of text that unique identifies a single line to include.
classThe class settings to be passed to rendered HTML tag.
indent0The level of indenting to apply to the included text.
languageNoneThe language to use for highlighting, if not supplied it will be inferred from the extension (if possible).
footerText to include after to the included text.
captionNoneThe caption to use for the listing content.
blockNoneSpace separated list of input file block names to include.