: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 Standard: Model
=============================

This document extends the :doc:`afsim_documentation_standard`.

The **\.. model::** directive is used to document a model and its syntax.
This directive creates a model index entry and a link target, referenceable with the **:model:** role.
For :ref:`model commands<docs/developer/standard_documentation_command:Model Commands>` implemented by a given model,
command documentation should be included with the corresponding model documentation.

Model Markup
------------

.. list-table::
   :class: example-rst
   :header-rows: 1

   * - **Example**
     - **Markup**

   * - .. parsed-literal::

         Command Block with Model Parameter

         :command:`platform` CESSNA_172 :model:`WSF_PLATFORM`
            side blue # A model sub-command
            ...
         end_platform

     - ::

         .. model:: platform WSF_PLATFORM

   * - ::

         ... <model-name>

     - ::

         .. model:: <model-type> <model-name>

Cross-Referencing Models
------------------------

.. list-table::
   :class: example-rst
   :header-rows: 1

   * - **Markup**
     - **Result**

   * - .. code-block:: rest

         Model Cross-Reference

         See :model:`WSF_GEOMETRIC_SENSOR`

     -   Model Cross-Reference

         See :model:`WSF_GEOMETRIC_SENSOR`

Model Page Structure
--------------------

The contents of a model page will vary by model. However, each page should be structurally similar.
Model pages will be named in lowercase, but the page title and the model documentation itself will be fully capitalized.
Some models implement commands specific to the model, while simple models do not. Meaning the documentation for some models
may simply note that the model exists and reference its usage in a related script class and/or command.

.. topic:: Example Pages

   .. hlist::
      :columns: 4

      * :doc:`../wsf_geometric_sensor`
      * :doc:`../wsf_platform`
      * :doc:`../wsf_p6dof_mover`

.. topic:: Page Template

   File: <model-name>.rst

   .. code-block:: rest

      <model-name>
      ============

      .. model:: <model-type> <model-name>

      .. parsed-literal::

         <block-command> <object-name> <model-name>

            :command:`<model-command-1>`
            :command:`<model-command-2>`

            ...

         end_<block-command>

      Overview
      --------

      ...

      Commands
      --------

      ...