AFSIM Sphinx Extensions

This is a component of the Documentation Guide.

A key feature of Sphinx is its extensibility. Through Sphinx extension, it is possible to support additional markup beyond what is provided by the base reStructuredText markup.

Using Sphinx Directives and Roles, these extensions may serve a variety of purposes.

Several AFSIM-Specific custom Sphinx extensions are implemented and maintained in the following directory:

afsim/cmake/Modules/sphinx/extensions

Note

The following sections summarize the capabilities and intended purpose of each AFSIM Sphinx extension. For examples demonstrating the capabilities listed below, see the AFSIM Documentation Standard.

wsf

wsf (wsf.py, wsf-python<#>.py) is the primary extension supporting AFSIM object type declaration and cross-references. It facilitates documentation of AFSIM commands, models, and script classes through custom Sphinx markup:

  • Cross-Referencing Directive/Role Pairs:

    • .. argtype:: / :argtype:

    • .. class:: / :class:

    • .. command:: / :command:

    • .. demo:: / :demo:

    • .. method:: / :method:

    • .. model:: / :model:

  • Grouping / Blocking Directives:

    • .. block::

    • .. begin::

    • .. end::

  • Additional Directives:

    • .. commandlisting:

    • .. inputs:

    • .. methodlisting:

  • Additional Roles:

    • :index:

afsim-issue-role

This extension (afsim-issue-role.py) introduces the :issue: role to the AFSIM ReStructuredText Markup.

This role is intended for use within changelog entries to conveniently link Issue IDs to their external issue definition pages.

See Issue for markup and examples.

Note

This feature is not supported prior to AFSIM 2.8.0.

afsim-autosectionlabel

afsim-autosectionlabel.py enhances the function of the :ref: role to support cross-references to sections in other documents directly - without the need for explicit labels. It additionally adds cross-reference support for duplicate sections in a single document.

See Automatic Section Labels for markup and examples.

Note

This feature is not supported prior to AFSIM 2.8.0.