Documentation Guide

Documentation is a fundamental component of AFSIM for all who interact with the software.

Foremost, it is the primary medium through which the user will discover and reference AFSIM capabilities, and keep up-to-date with changes to the software as new features are introduced.

Beyond that, because AFSIM is the product of many contributions, made by many developers, over many years, well maintained documentation is a critical tool to the developer for both the maintenance and extension of the software.

With an understanding of documentation’s core function to all parties using and/or supporting AFSIM, it follows that a standard must be established, understood, and practiced to ensure that AFSIM documentation is maintainable, consistent, and universally navigable.

This guide is provided to describe the system under which all AFSIM Documentation (the documentation) is supported. Familiarity with this guide and its components will enable the developer to more effectively author and navigate AFSIM documentation.

Introduction

The documentation is delivered and available to the user in multiple formats. While the documentation is delivered in a unified state for each format, it is not practical to maintain the documentation in this way. Instead, the documentation is maintained across many, relatively small, ReStructuredText files, and generated using Sphinx and other tools. (See Documentation Generation)

In order to define an AFSIM Documentation Standard, ReStructuredText, Sphinx, and the various capabilities introduced by AFSIM Sphinx Extensions must be detailed.

Note

For detailed instructions on software and version requirements required to build documentation, see Build Instructions.

ReStructuredText

ReStructuredText (RST) is described as, “an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system”. RST is a component of docutils, an open source Python project, described as, “a modular system for processing documentation into useful formats”.

The exhaustive RST markup specification is described in docutils.

Sphinx

Though documentation generation varies by final format, all generation for AFSIM documentation begins with Sphinx. Sphinx is an open source Python project licensed under BSD-3-Clause. It uses RST as its markup language and includes built-in support for enhanced RST markup, natively expanding the capability provided by docutils. It is capable of generating documentation in a variety of formats, including HTML and LaTeX, among others.

Importantly, Sphinx is designed for extensibility and provides inter-document cross-referencing support.

In support of AFSIM documentation, the AFSIM source includes AFSIM Sphinx Extensions which define custom markup in addition to markup provided by Sphinx and docutils.