Documentation#

Design#

Rule#

Each rule must have an associated documentation file with the following sections:

  • Description: Description of the checks performed by the rule.

  • Rationale: Purpose of the rule.

  • Verification: How the verification is performed, which is particularly useful when it is not possible to automate completely the verification of a rule.

  • Resolution: How to fix the violation.

  • Customization: How to customize the rule, when applicable. The most common means are as follows:

    • Checked elements: For example, model elements that should comply to a given naming rule.

    • Sub-classing: Modify the default behavior of a rule by deriving a new one and redefining one or more functions.

The documentation file also contains metadata for queries or building tables.

The files are located in the ./doc/source/rules directory. The structure of this directory must match the structure of ./src/ansys/scade/design_rules.

Each directory containing rules’ documentation must have a index.rst file that provides a general overview and a table listing all the contained rules.

Metric#

Each metric must have an associated documentation file with the following sections:

  • Description: Description of the metric.

  • Computation: How the computation is performed.

  • Customization: How to customize the metric, when applicable.

The documentation file also contains metadata for queries or building tables.

The files are located in the directory ./doc/source/metrics. The structure of this directory must match the structure of ./src/ansys/scade/design_rules/metrics.

The directory containing metrics’ documentation must have a index.rst file that provides a general overview and a table listing all the contained metrics.

Tools#

The pre-commit hook update_doc ensures each metric or rule is documented and consistent. It is based on naming rules.

When a rule has no associated documentation, the hook creates a new file with all sections and metadata. Then, it replicates information from the rule’s Python file: * id * label * description * filename * class

The part of the updated description is delimited by:

  • The beginning of the section Description or the tag .. start_description if present

  • The end of the section Description or the tag .. end_description if present.

Any additional description text outside those limits is preserved when updating the documentation.

This tool also creates a default index.rst file when it does not exist.