Several files use embedded reStructuredText blocks in order to use the
:doc: directive to reference other markdown files using a relative path.
MyST Parser supports a similar feature using the standard Markdown
autolink (angled bracket) syntax, so use this instead as it is cleaner.
Both methods use the first heading of the linked file as the text shown
in the reference, though MyST Parser also supports the standard [link
text](../path/to/file.md) syntax to explicitly set the link text.
Note that when using the autolink syntax, `project:` must be prepended
to the relative path as it expects a URI scheme for all autolinks. This
is not required when using the separate text and URI syntax.
Before:
```{eval-rst}
Example text :doc:`../relative/path`.
```
After:
Example text <project:../relative/path.md>
Using the Markdown syntax also avoids formatting issues if any plain
text in the eval-rst block uses Markdown formatting syntax where they
would unintentionally be parsed differently due to text being parsed as
reStructuredText.
Some :doc: instances still remain as they are used within reST style
tables in an eval-rst block, so these were left as is since the Markdown
syntax would be invalid in that context.
[1]: https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#autolinks
Change-Id: I8828bf7efe13de6d6f628f6b64151fbd25289fa5
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/88618
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Nicholas Sudsgaard <devel+coreboot@nsudsgaard.com>
49219f1ce1
