diff --git a/docs/Contributors_Guide/documentation.rst b/docs/Contributors_Guide/documentation.rst index 6b43810c3..89373f480 100644 --- a/docs/Contributors_Guide/documentation.rst +++ b/docs/Contributors_Guide/documentation.rst @@ -218,7 +218,7 @@ for more information. **What to bold:** - * Variables (e.g. **MET_INSTALL_DIR, INPUT_BASE, METCALCPY_HOME**, etc.) + * Environment Variables (e.g. **MET_INSTALL_DIR, INPUT_BASE, METCALCPY_HOME**, etc.) * Filenames (**line_defaults.yaml, contour_defaults.yaml, defaults.conf**, etc.) Italics @@ -395,6 +395,20 @@ resulting in the following displayed text: See `Overleaf's Guide - Matrices `_ for more information. +Literal Include +--------------- + +This feature is used often in the Release Guide, but there are other places it could be useful. +Using a literal include ensures only having to update the documentation in one place. +It is important to use a relative path (i.e. "../../") to get to the correct +directory of the file being referenced in the literal include. This will keep the +file linking to the correct version and branch. + +As an example, refer to the METplus User's Guide. See this +`line `_ +in the PointStat Wrapper Use Case documentation, which uses RST's :code:`.. literalinclude::` +and renders the text of the referenced file in this +`section `_. Literal Blocks -------------- @@ -425,6 +439,54 @@ and `literal blocks `_ for more information. +Substitution References +----------------------- + +Substitution references are replacements in the text as defined in the :code:`rst_epilog` +in the **docs/conf.py** file. For example, instead of hard coding the MET version in +the METplus documentation, a variable :code:`met_version` can be set to a value +(e.g. 12.0.0) in the **docs/conf.py** file in the following way: + +.. code-block:: ini + + met_version = 12.0.0 + +Then, this variable is used in the :code:`rst_epilog` to set up the substitution, +along with other variables. For example, in the **docs/conf.py** +file the following is defined: + +.. code-block:: ini + + rst_epilog = f""" + .. |copyright| replace:: {copyright} + .. |author_list| replace:: {author_list} + .. |release_date| replace:: {release_date} + .. |release_year| replace:: {release_year} + .. |release_info| replace:: {release_info} + .. |python_version| replace:: {python_version} + .. |met_version| replace:: {met_version} + """ + +The value 12.0.0 would then be replaced in the documentation wherever +:code:`|met_version|` is used in .rst files. For example: + +.. code-block:: ini + + MET version |met_version| or above + +There are some +`reserved substitution variables `_ +in Sphinx. These variables are +:code:`|release|`, :code:`|version|`, :code:`|today|`, and +:code:`|translation progress|`. Reserved substitution variables do not +need to be added to :code:`rst_epilog`, but other variables do. + +See +`Substitutions `_ +and +`rst_epilog `_ +for more information. + Line Blocks -----------