Documentation Linking

This document is a component of the AFSIM Documentation Standard.

Terms:

  • Target: Targets may be linked to, and may be internally or externally defined.

  • Link: Links are reference to targets, rendered as clickable hyperlinks.

  • Label: Labels define internal targets. The target is the next element after the label.

  • Cross-Reference: Cross-references are links to internal targets.

  • Internal: Refers to targets defined within the documentation.

  • External: Refers to other resources, usually websites, defined outside of the documentation.

External Linking

External linking markup is provided by ReStructuredText, which refers to external link targets as Hyperlink Targets. These may be linked to by Hyperlink References.

Markup

Result

 
External Linking

Learn more about `RestructuredText`_!

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

External Linking

Learn more about RestructuredText!

Internal Linking

Internal linking, or cross-referencing, is a core feature of the AFSIM Documentation. Through internal linking, the documentation is more navigable, and therefore more valuable to the user.

Internal linking markup is available in multiple forms through a number of sources.

Intra-Document Cross-Referencing

Also known as short-hand cross-referencing, this is the simplest form of cross-referencing. Provided by reStructuredText and docutils, this markup renders a link to a target in the same file.

Within a given document, a section may be referenced without the need for an explicit label. Implicit labels matching the section name are generated automatically by docutils.

Markup

Result

 
Intra-Document Section Linking

Link to this section:

`Intra-Document Cross-Referencing`_

Intra-Document Section Linking

Link to this section:

Intra-Document Cross-Referencing

To reference an arbitrary location or element within a given document, an explicit link target, or label, must be defined immediately before the desired target.

Markup

Result

 
Intra-Document Linking

.. _paragraph:

This paragraph is the link target

...

Go back to the paragraph_.

Intra-Document Linking

This paragraph is the link target

…

Go back to the paragraph.

Inter-Document Cross-Referencing

Sphinx offers improved cross-referencing capability through the use of roles.

doc

The :doc: role is available to reference a specific document within the documentation build.

The argument passed to this role must be a valid document name, omitting the file extension. The name must be prepended with a relative path from the referencing document, or the absolute path from the documentation root (/docs/…).

Markup

Result

 
Referencing a Document

This document is a component of

the :doc:`afsim_documentation_standard`.

Referencing a Document

This document is a component of

the AFSIM Documentation Standard.

Note

For this example, the referenced document is located in the same directory as the referencing document. A prepended path is required only when the referenced document is in a different directory.

Tip

To ascend the directory tree, ../ may be provided as part of the relative path. Alternatively, paths beginning at the documentation root (/docs/…) are always valid.

ref

Also included with Sphinx Markup, the :ref: role, may be used to reference any explicit target, regardless of the target’s location.

Markup

Result

 
Inter-Document Cross-Reference

To view the list of markup sources:

See: :ref:`Markup Sources <Markup Table>`

Inter-Document Cross-Reference

To view the list of markup sources:

See: Markup Sources

Referencing Sections

Important

The following markup is replaced by Automatic Section Labels. It is documented here because it appears frequently throughout the AFSIM documentation.

To reference a section outside of the current document, an explicit link target / unique label must be placed immediately before the section name.

To ensure that a given label is globally unique, a robust naming convention should be preferred, including both the section name, and the name of the parent document.

To support an example, a label has been implemented for this section:

.. _DOCUMENTATION_LINKING REFERENCING SECTIONS:

Referencing Sections
^^^^^^^^^^^^^^^^^^^^

...

With the label provided above, a cross-reference to this section from another document is now possible.

Note

For this example, the reference is made from within the same document. Identical markup is used to reference this section from other documents.

Markup

Result

 
Inter-Document Section Linking

Global link to this section:

:ref:`DOCUMENTATION_LINKING REFERENCING SECTIONS`

Inter-Document Section Linking

Global link to this section:

Referencing Sections

See Also

Automatic Section Labels

Automatic Section Labels

Often, it is desirable to reference a section of a different document. While this is supported through the previous markup, it requires that an explicit link target be written for any such section. Because this is common and requires globally unique labels, it results in maintenance challenges.

The AFSIM Sphinx Extension, “afsim-autosectionlabel” was created to overcome this issue. This extension uses the :ref: role with AFSIM Markup to link to sections outside of the current document, without requiring the developer to create an explicit link target above the section title. This usage of ref requires that the argument is a valid file path and name, starting at the documentation root (docs/…), with a single : between the file name (extension omitted) and section name. Aliases/Captions are supported but not required.

Markup

Result

 
Inter-Document Section Link

See :ref:`Platform Overview<docs/platform:Overview>`

Inter-Document Section Link

See Platform Overview

Additionally, afsim-autosectionlabel supports references to duplicate sections for instances where a given section recurs in a single document. Any reference to the first occurrence of a given section follows the markup described above, while duplicate sections are referenceable through insertion of a : and the parent section name.

Note

This capability is provided for full support of certain legacy documentation. Identically named sections in a single document should be avoided.

Target File

Reference Markup

 
.. example.rst

Title
=====

Sec 1
-----

Summary
"""""""

Sec 2
-----

Summary
"""""""

Reference duplicate section in example.rst







:ref:`Summary 1<docs/example:Summary>`





:ref:`Summary 2<docs/example:Sec 2:Summary>`

Note

Automatic Section Labeling is not supported prior to AFSIM 2.8.0.

AFSIM Object Cross-Referencing

AFSIM Object Links (links the documentation of AFSIM defined objects) are fundamental to the utility of the AFSIM Documentation. Markup and examples are provided in each object’s respective categorical standard. Linking markup varies by object, but is generally similar to the markup described above. Newly introduced object types should support cross-referencing and adhere to the general markup described below.

Intra-Document

Within a given page, shorthand-markup may be used to cross-reference an object

Template Markup

Template Result

 
.. <object-type>:: <object-name> [<object-args>]

...

See `<object-name>`_

<object-name> [<object-args>]

...

See <object-name>

Inter-Document

Cross-referencing objects defined in a separate document requires the use of AFSIM Markup, more specifically, custom Sphinx roles. Each object type defines a unique role which may be used to cross-reference a defined object of that type.

Template Object Document

Template Reference Markup

 
.. <file-name>.rst

...

.. <object-type>:: <object-name> [<object-args>]

Reference to object defined in <file-name>.rst

...

:<object-type>:`<object-name>`