Documenting MOOSE
MOOSE and MOOSE-based applications generally focus on creating C++ objects (e.g., Kernels, BCs, etc.), so it is important that these objects are documented to allow other developers and users to understand the purpose of these objects. The MooseDocs System aims to make documenting objects straightforward and natural. Moreover, accessing the object documentation is simple and allows for documentation to remain up-to-date as the code continues to advance.
In order to ensure that MOOSE documentation continues to improve, requirements exist for documenting new and changing code within MOOSE:
Any new MooseObject must have descriptions for the class and all parameters.
Any new MooseObject must also include an associated markdown description page.
Developers who modify existing classes should update the existing markdown documentation file.
All new tests must contain a 'requirement' and link to 'design' and 'issues'.
MooseObject C++ Documentation
The first step is to add documentation for your application in the validParams function. This is done by adding parameter documentation strings and calling the class description method.
A description of each parameter should also be provided when they are added with the various add methods of the InputParameters object. For example, in the BoxMarker the following parameter documentation is added, which is then present in the parameter summary table of the generated site.
params.addRequiredParam<RealVectorValue>(
"bottom_left", "The bottom left point (in x,y,z with spaces in-between).");The string supplied in this function will appear in the parameter tables within the documentation that is generated. For example, see the parameter table for BoxMarker.
Secondly, a short description of the class should be supplied in the addClassDescription function. For example, the Diffusion object has the following class description:
params.addClassDescription("The Laplacian operator ($-\\nabla \\cdot \\nabla u$), with the weak "When the documentation for this object is generated, this string is added to the first portion of the page and the system overview table. For example, the Kernels overview includes a table with each object listed; the table includes the class description from the source code.
Markdown Documentation
Clear and consistent documentation is a necessary component of code development within MOOSE. It is expected that developers submitting new MooseObjects (e.g., Kernel or BoundaryCondition) to the framework or modules will create a corresponding markdown file, using MOOSE Markdown Specification (MooseDown), to document the new classes.
The documentation for the classes within MOOSE and the modules are located within the "doc" directory where the class is registered: "framework/doc" contains all core MOOSE level objects, "modules/tensor_mechanics/doc" contains object for the tensor mechanics modules, etc.
When adding documentation, the MOOSE modules executable must exist; this is accomplished by using the following commands:
cd ~/projects/moose/modules
make -j16 # 16 should be replaced by the number of cores on your system
If you are writing a documentation page for a new class with MOOSE or the modules, you can use the MooseDocs executable to build a documentation stub for your new class:
cd ~/projects/moose/modules/doc
./moosedocs.py check --generate
This generate command needs to be run only when you add a new object (e.g., Kernel, BoundaryCondition, etc.) to your application.
After the stub files have been created, a local, live version of the website should be used to add content (see the Live Website section below).
Live Website
A local website can be created and served; this is done by running the following commands. When this command completes, which can take several minutes, a message will be printed and the site will be hosted at http://127.0.0.1:8000:
cd ~/projects/moose/modules/doc
./moosedocs.py build --serve
Once the server is running, the markdown files within the repository may be modified. When changes are saved, the local server will automatically update the content. The content added or modified should follow the Standards for Documentation Pages guidelines.
Requirement, Design, and Issues
MOOSE follows strict software quality standards. To meet these standards, every test within MOOSE must provide three items with each test of the test specification.
requirement: A description of the "requirement" that the test is testing. The text for the requirement must be listed in the test specification file ("tests" file).
design: A list of markdown files associated with the test that explain the systems, objects, and design documents. The file paths do not need to be complete, but must be unique.
issues: A list of github issues that are associated with the test and items being tested.
These items are provided in the associated "tests" file. For example,
[Tests]
[./my_test]
type = 'CSVDiff'
input = 'my_test.i'
csvdiff = 'my_test.csv'
requirement = "MyObject shall do some kind of thing. Maybe this description has "
"multiple lines."
design = 'MyObject.md some_relevant_file.md'
issues = '#1234 #1235 #1236'
[../]
[]