Replace italics below with details for this issue.
Describe the Task
Literal include
This feature is used often in the Release Guide. But there are other places it can also be used.
Using a literal include ensures only having to update the documentation in one place.
It is also important to use a relative path (e.g. "../../") 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.
Julie curated this example:
As an example, refer to the METplus User's Guide. See this line in the PointStat.py which uses RST's .. literalinclude:: and renders on the web in what appears to be a code block in this section.
==============
Substitution References
(This section can be included before or after the Literal Blocks)
Substitution references are replacements in the text as defined in the rst_epilog in the docs/conf.py file. For example, instead of hard coding the MET version in the METplus documentation, a variable met_version can be set to a value (e.g. 12.0.0) in the docs/conf.py file in the following way:
met_version = 12.0.0
Then, this variable is used in the rst_epilog to set up the substitution, along with other variables. For example, in the docs/conf.py file the following is defined:
The value 12.0.0 would then be replaced in the documentation wherever |met_version| is used in .rst files. For example:
MET version |met_version| or above
There are some reserved substitution variables in Sphinx. These variables are release|, |version|, |today|, and |translation progress|. Reserved substitution variables do not need to be added to rst_epilog, but other variables do.
[ ] Submit a pull request to merge into develop.
Pull request: feature <Issue Number> <Description>
[ ] Define the pull request metadata, as permissions allow.
Select: Reviewer(s) and Development issues
Select: Repository level development cycle Project for the next official release
Select: Milestone as the next official version
[ ] Iterate until the reviewer(s) accept and merge your changes.
Replace italics below with details for this issue.
Describe the Task
Literal include This feature is used often in the Release Guide. But there are other places it can also be used. Using a literal include ensures only having to update the documentation in one place. It is also important to use a relative path (e.g. "../../") 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.
Julie curated this example: As an example, refer to the METplus User's Guide. See this line in the PointStat.py which uses RST's
.. literalinclude::
and renders on the web in what appears to be a code block in this section.==============
Substitution References (This section can be included before or after the Literal Blocks)
Substitution references are replacements in the text as defined in the
rst_epilog
in the docs/conf.py file. For example, instead of hard coding the MET version in the METplus documentation, a variablemet_version
can be set to a value (e.g. 12.0.0) in the docs/conf.py file in the following way:Then, this variable is used in the rst_epilog to set up the substitution, along with other variables. For example, in the docs/conf.py file the following is defined:
The value 12.0.0 would then be replaced in the documentation wherever
|met_version|
is used in .rst files. For example:There are some reserved substitution variables in Sphinx. These variables are release|, |version|, |today|, and |translation progress|. Reserved substitution variables do not need to be added to rst_epilog, but other variables do.
See Substitutions and rst_epilog for more information.
Time Estimate
Estimate the amount of work required here. Issues should represent approximately 1/2 day of work.
Sub-Issues
Consider breaking the task down into sub-issues.
Relevant Deadlines
List relevant project deadlines here or state NONE.
Funding Source
Define the source of funding and account keys here or state NONE.
Define the Metadata
Assignee
Labels
Projects and Milestone
Define Related Issue(s)
Consider the impact to the other METplus components.
Task Checklist
See the METplus Workflow for details.
feature_<Issue Number>_<Description>
feature <Issue Number> <Description>