starlingx/docs
Code Issues Proposed changes

Escape rST (r5, r6, dsR6)

Browse Source 
Changes made under https://review.opendev.org/c/starlingx/docs/+/839788
are incompatible with excluding rST error samples from html checks.
Use HTML comments and escape codes to bypass error scanning.

Signed-off-by: Ron Stone <ronald.stone@windriver.com>
Change-Id: I307643a7c916537eea89cf36e5497dffbd26c8de
This commit is contained in:
Ron Stone 2022-04-29 08:30:04 -04:00
parent 171377433c
commit 76e85f7532
2 changed files with 14 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
doc/source/contributor/doc_contribute_guide.rst
View File

@ -335,8 +335,7 @@ You can build the HTML documentation locally using the ``tox -e docs`` command.
After every successful build, several quality checks are performed against the After every successful build, several quality checks are performed against the
build HTML output. build HTML output.
.. code-block:: none .. parsed-literal::
:emphasize-lines: 3,4,10
Checking for "grey bar" formatting errors in output ... Checking for "grey bar" formatting errors in output ...
Found 2 HTML file(s) with greybar formatting issues: Found 2 HTML file(s) with greybar formatting issues:
@ -347,7 +346,7 @@ build HTML output.
Checking for unexpanded substitution errors in output ... Checking for unexpanded substitution errors in output ...
Found 1 HTML file(s) that may have unexpanded substitution(s): Found 1 HTML file(s) that may have unexpanded substitution(s):
./node_management/kubernetes/hardware_acceleration_devices/enabling-mount-bryce-hw-accelerator-for-hosted-vram-containerized-workloads.html:| 1d02 | |SATA| controller | Intel Corporation | ./node_management/kubernetes/hardware_acceleration_devices/enabling-mount-bryce-hw-accelerator-for-hosted-vram-containerized-workloads.html:| 1d02 | |html-pipe|\ SATA\ |html-pipe| controller | Intel Corporation |
Correct the issue(s) in the corresponding rST file(s). Correct the issue(s) in the corresponding rST file(s).
@ -389,15 +388,15 @@ This sample shows three problems.
- As above, find the problem in the appropriate - As above, find the problem in the appropriate
:file:`.rst` file by examining the :file:`.html` file reported. Look for :file:`.rst` file by examining the :file:`.html` file reported. Look for
code fragments associated with ``.. include::`` directives such as code fragments associated with ``.. include::`` directives such as
``:start-after:`` and ``:end-before:`` that have been exposed in the :start\ |html-comment|-after: and :end\ |html-comment|-before:
final output. that have been exposed in the final output.
Correct the issues by making the code comply with the documentation at: Correct the issues by making the code comply with the documentation at:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#include https://docutils.sourceforge.io/docs/ref/rst/directives.html#include
* - Substitution errors * - Substitution errors
- Scans the output for potential unexpanded substitutions such as - Scans the output for potential unexpanded substitutions such as
``|prod|`` and reports which files they were found in, along with the |html-pipe|\ prod\ |html-pipe| and reports which files they were found in, along with the
offending lines of HTML. offending lines of HTML.
.. note:: .. note::
@ -406,7 +405,7 @@ This sample shows three problems.
problem needs to be fixed. problem needs to be fixed.
- As above, find the problem in the appropriate :file:`.rst` file by - As above, find the problem in the appropriate :file:`.rst` file by
examining the :file:`.html` file reported. Look for ``|<text>|`` code examining the :file:`.html` file reported. Look for |html-pipe|\ <text>\ |html-pipe| code
exposed in the output. In the corresponding :file:`.rst`, find and exposed in the output. In the corresponding :file:`.rst`, find and
correct the issue. correct the issue.

8
doc/source/shared/strings.txt
View File

@ -38,4 +38,12 @@
<style>table.docutils tr.row-odd {background-color: #fff;}</style> <style>table.docutils tr.row-odd {background-color: #fff;}</style>
.. |html-comment| raw:: html
<!---->
.. |html-pipe| raw:: html
&#124;
.. |optional| replace:: **Optional step:** .. |optional| replace:: **Optional step:**