:orphan:

.. ****************************************************************************
.. CUI
..
.. The Advanced Framework for Simulation, Integration, and Modeling (AFSIM)
..
.. The use, dissemination or disclosure of data in this file is subject to
.. limitation or restriction. See accompanying README and LICENSE for details.
.. ****************************************************************************

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
:doc:`a standard<afsim_documentation_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 :doc:`Documentation Generation<documentation_generation>`)

In order to define an |AFSIM_DOCUMENTATION_STANDARD|, ReStructuredText_, Sphinx_,
and the various capabilities introduced by |AFSIM_SPHINX_EXTENSIONS| must be detailed.

.. |AFSIM_DOCUMENTATION_STANDARD| replace:: :doc:`afsim_documentation_standard`
.. |AFSIM_SPHINX_EXTENSIONS| replace:: :doc:`afsim_sphinx_extensions`

.. note:: For detailed instructions on software and version requirements required to build documentation, see :doc:`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_.

.. _docutils: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

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 :doc:`cross-referencing<documentation_linking>` support.

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