Document Generation Utility

This application is used to drive the documentation system, which allows data available in rapyds to be inserted directly in high quality documents. The system relies on the Sphinx engine, which in turn is built using the docutils framework.

Typical Use Cases

You would typically use this functionality in the following situations:

  • Writing a model description report, which references various components of the underlying model data.

  • Writing a validation report, which typically includes results from multiple application runs.

  • Combining output from multiple application runs into a single analysis report.

Note

When results form only a single application is used, the built-in documentation mode for that application can be used, and there is no need to create a separate input script. See Activating documentation input and the corresponding Document generation mode mode.

Creating an Input Module

An empty input module can be created using the manager utility:

oscar5 MY_REACTOR.manager docgen MODULE_NAME [options]

This command the following optional arguments:

--package <str>

The subpackage to which this module should be added. The default value is ‘docs’.

--description <str>

A short description of the input module.

--template <str>

Path to template structure which is used to generate the documentation input skeleton.

A typical input module has the following form:

import applications.docgen as app
from core import *
# import some result token(s)
from applications.critical_case import multiplication_factor

# Create parameter set
doc_param = app.parameters()

# Base documentation skeleton
doc_param.documentation_templates = '/full/path/to/template'

# Set to which files the pre processor should be applied
doc_param.template_pre_processor_filter = 'conf.py'

# Extract results and bind to variables
keff = doc_param.extract(multiplication_factor, '/full/path/to/results')
doc_param.register('My_keff', keff)
# etc

if __name__ == '__main__':
 app.main(parameters=cpp)

The input module only binds variables to be used in the document, and provides an interface for generating and viewing the result. Most of the actual document contents, is specified within the usual Sphinx structure, which typically has the following form:

WORKING_DIRECTORY
      + - build
      + - source
        + - images
        + - static
          - index.rst
          - conf.py
          - .results.pkl
      - Makefile | make.bat

Here,

  • WORKING_DIRECTORY, is the root directory as set using doc_param.working_directory.

  • The build directory is were the generated document(s) will be written too.

  • All inputs are contained within the source directory. It usually has two (possibly empty) subdirectories: images, which contain images that should be included in the document, and static, which contains style elements.

  • A master reStructuredText source file (index.rst in this case, but can be customized using doc_param.master_document). This file describes the document’s content, and can include other reStructuredText source files.

  • The conf.py is a Sphinx configuration file, which contains numerous customization options, such as setting the HTML theme, configuring the LaTeX (PDF) output, etc.

  • A .results.pkl file, which is a binary archive collecting all the bound variables. It is generated automatically (and updated) during the pre-processing phase.

  • The Makefile (make.bat on Windows), is the Sphinx build script, which describes all the generator targets (html, latexpdf, etc.)

Input Parameters

In the following doc_param denotes a docgen parameter set, created as follows:

import applications.docgen as app

doc_param = app.parameters()

This application supports all the following parameters:

doc_param.project_name

: string

This parameter is used in certain input templates to name input and output files. If not specified, it will be assigned the input module name.

doc_param.working_directory

: directory

Specify where the documentation tree should be created. It is usually specified relative to the script:

parameters.working_directory = core.utilities.path_relative_to(__file__, 'my_working_directory')
doc_param.documentation_template

: directory

A base document source tree which is used to initiate the source tree associated with the current document.

There are two built-in templates:

  1. A basic one:

    doc_param.documentation_template = '%AUTODOC/templates/basic'

  2. An advance one containing custom elements to produce a specific report format:

    doc_param.documentation_template = '%AUTODOC/templates/report'

Both of these can also be used as a starting point to produce your own template.

doc_param.master_document

: string

 = index

Name of the document source file that acts as the entry point for the document. It contains either the entire document source, or an toctree directive included other source files.

doc_param.template_pre_processor_filter

: regex

Filter that determines to which files the pre-processor should be applied. For example, when only directives are used in the rst files, then the pre-processor should only be applied to the conf.py file:

doc_param.template_pre_processor_filter = 'conf.py'

Binding variables to be used in the document

doc_param.extract(output_token, result=None)

Convenience method used to extract output from a result set.

Parameters:

  • output_token – Token indicating what should be extracted.

  • result – Target application result. If not specified, output_token will be extracted from the attached application.

Returns:

A reference to the output value.

There are a number of ways to assign the result:

  1. By passing the absolute path to the result (.res) file, e.g:

    v = doc_param.extract(token, '/path/to/MY_REACTOR/WORKING_DIRECTORY/TARGET_MODE/project_name.res')

  2. Importing the target input module and extracting the results:

    from . import target_module  # assuming app sits in same package

v = doc_param.extract(token, target_module.parameters.create_app(target_mode='TARGET_MODE').get_results())

Note

The returned value can be combined with other output value references (or static values) in arithmetic expressions to produce new values.

Attention

This only serves to extract the result, and does not bind it to document variable set. Use the set() or register() for this purpose.

doc_param.set(name, value)

Binds a variable for use in the document.

Parameters:

  • name (str) – The variable name, which will be used to reference value in the document.

  • value – The variable value, which can be any Python data type, a result token (as returned by doc_param.extract()), or combination of such tokens.

The variable value con be referenced using the ${name} convention in the document itself. See Variable tokens.

doc_param.register(name, expression, description=None, ranges=None, uncertainty=None, fmt=None, results=None)

Similar to doc_param.set, but with the possibility to pass more information.

Parameters:

  • name (str) – The variable name, which will be used to reference expression in the document.

  • expression – The variable value, which can be a raw variable token (as passed as input to doc_param.extract()), a result token (as returned by doc_param.extract()), or combination of such tokens.

  • description (str) – Optional description of the variable.

  • ranges – The range (upper and lower bound) in which the value should fall.

  • uncertainty – The typical uncertainty associated with the parameter value.

  • fmt – How the value should be formatted in the document.

  • results – Similar to the result variable in doc_param.extract().

The variable value con be referenced using the ${name} convention in the document itself. See Variable tokens.

Command Line Usage

This application has two sub-modes:

pre

Updates the source tree and bound variable set.

execute

Run the documentation generation and view the generated document(s).

pre

This mode accomplishes the following:

  1. Create the source tree from the doc_param.documentation_template if it does not exist.

  2. Runs the pre-processor on the files specified in doc_param.template_pre_processor_filter.

  3. Updates the bound variable set, and writes it to a .results.pkl object in the source tree.

execute

This modes calls the document generator engine Sphinx, which produces the final document(s). It accepts the following flags:

--force

Force running the pre-processor, and rebinding of variables. This is required if anything in the doc_param.documentation_template changed, or if the value of any bound variable changed.

--skip-html

Don’t generate HTML output.

--skip-pdf

Don’t generate LaTeX output.

--show

View the generated output. On most platforms, it will be opened in a browser window.

Typical command line usage

oscar5 MY_REACTOR.docs.my_module execute --force --show

Examples

Extra Resources