Inclusions

There are two different inclusions that occur in ICG Sphinx docs: inclusion of code input files (*.dat files etc.) in the docs (often in examples, but also elsewhere), and inclusion of *.rst fragments within other *.rst files. The latter are more esoteric and should really only be undertaken with advisement.

Code Inclusions

This section out of date; do not follow. Check with Chad.

Use the .. literalinclude:: directive to include a *.dat file in a doc. Note the option :language: fish must be included to get the appropriate command and FISH syntax highlighting.

load.dat

; fname: load.dat (3D)
;
; Restore the faulted BPM
; Apply gravitational load and test different joint friction angles
;=========================================================================
model restore 'fault'

; Fix row of balls at the bottom
ball fix velocity range position-z -6 -5.3

; Turn on gravity
model gravity 10

model solve ratio-average 1e-5

model save 'load_fric35'

; now set friction angle to 25 degrees
fracture property 'sj_fric' 0.466

; Decrease damping
ball attribute damp 0.1

; Do not use solve command since we expect unstable sliding
model cycle 10000

model save 'load_fric25'
;=========================================================================
; eof: load.dat (3D)

Use the ``.. literalinclude::`` directive to include a \*.dat file in a doc.
Note the option ``:language: fish`` *must* be included to get the
appropriate command and |fish| syntax highlighting.

**load.dat**

.. literalinclude:: /pfc/pfcmodule/test3d/tutorial_problems/joint_slip/load.dat
   :language: fish
   :name: exapp-inc

Also note that any link to a .. literalinclude:: that uses a :name:-based anchor must explicitly declare its label.

Also note that any link to a ``.. literalinclude::`` that uses a ``name``-
based anchor must :ref:`explicitly declare its label <exapp-inc>`.

*.rst Fragment Inclusions

• only use .. include:: if the included matter appears > 1 time

• anchor the inclusion with an explicit link above the .. include:: directive (which doesn’t support the :name: option)

• name files for included matter with underscore (_) as the first character and locate them in [source]/common/docproject/utilities

• at this time, thanks to indentation issues, using rst inclusion in commands is effectively infeasible

Building an inclusion used only once would be anomalous and is to be avoided.

The guidelines above are elaborated below.

Location

Please locate all inclusions, whether applicable to/used by only one code or more than one, in this location

[source]/common/docproject/utilities

Feel free to include a code name in the fragment file name (e.g., “_flac3_specific_material.rst”) if the content merits.

This is needed so that: a) all inclusions may be found in one place and b) so that all inclusions, which are “common” by their nature, are found in the common area of code — and are thus available to any document set, regardless of its configuration.

Name

Please, always name an inclusion unit with an underscore “_” at the start of its name. This is required because:

• files that start with “_” (that is, inclusions) are excluded from the doc set build list, by design, because an inclusion doc should only be processed as content sucked into another document, not as a source document in its own right.

• the convention makes it easy to identify an inclusion as an inclusion when reading the “host” source document that includes it.

No Anchors! And CAREFUL with Links

Do not put link targets inside included content. Reason: a link that jumps into an inclusion cannot be controlled with regard to the intended destination document. If docs A, B, and C all have an inclusion that has a link target in it, any attempt to link from doc D to that target will always “land” in the last-processed of documents A, B, and C. If a link needs to be built to go to the included content within a specific host document, put an explicit anchor (e.g., .. _targetlabel:) in front of the .. include:: directive in the host document.

.. _this-is-the-link-target:

.. include:: /common/docproject/utilities/_cyclesequence.rst

Note the .. include:: directive does not support the :name: option (which makes sense, because it would present the very problem under present discussion).

Not required, but helpful: put this comment on the first line of inclusion files.

.. this is an included document; do not put anchors in this file

With regard to hyperlinks within an inclusion that jump somewhere else: for that link to always work, it must be certain that its target will appear in any and every document set that may be built with that inclusion. If there is any chance that that is not true (or someday will not be true), better to avoid building the link.

Inclusion in Commands or FISH

Don’t try this. It almost certainly won’t work. The use of indentation levels to create parent-child relationships in keywords won’t support inclusions.