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>
- Update the instructions for building the documentation to account for
the switch from Recommonmark to MyST Parser
- Update outdated URLs
- Update various details to account for the current behavior and
features resulting from previous changes
Change-Id: I569862e30fb88a421ad2338aafabeaf3ea76836a
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/85857
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Elyes Haouas <ehaouas@noos.fr>
Reviewed-by: Maximilian Brune <maximilian.brune@9elements.com>
Reviewed-by: Alicja Michalska <ahplka19@gmail.com>
Commit 35599f9a66 (Docs: Replace Recommonmark with MyST Parser)
converted recommonmark style toctrees in bulk using a script. This was
done by searching for lists of references, which is how recommonmark
denoted toctree entries. However, this also converted lists of external
URLs, which would not normally be included in the toctree. Revert these
cases back to lists of URLs as they were before the migration.
Change-Id: Ie4da3d908d4b84c2c7e3572fb4baaeed1f8edb45
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/84244
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
This fixes the following MyST Parser warnings:
- Non-consecutive header level increase
- Document headings start at H2, not H1
The header levels (the number of "#" characters before a heading) are
intended to form a logical hierarchy of each section and subsection in a
document. A subsection typically should have a header level one more
than its parent section. Most of these warnings are caused by extra "#"
characters, which were simply removed, or sections missing a "#"
character to make it fall under its parent section.
Notable changes:
getting_started/kconfig.md: Changed the header level of the "Keywords"
section from 2 to 3 to fall under "Kconfig Language" (level 2), and
increased the level of each keyword from 3 to 4 to remain under
"Keywords". This also fixes the warnings of "H3 to H5" increases, since
the Usage/Example/Notes/Restrictions sections for each keyword had a
level of 5.
soc/intel/cse_fw_update/cse_fw_update.md: Changed the first line to a
top level header acting as the title of the document. Without this
soc/intel/index.md displays all the level 2 headers in this document
instead of a single link to cse_fw_update.md.
Change-Id: Ia1f8b52e39b7b6524bef89a95365541235b5b1b9
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/83382
Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Elyes Haouas <ehaouas@noos.fr>
Recommonmark has been deprecated since 2021 [1] and the last release was
over 3 years ago [2]. As per their announcement, Markedly Structured
Text (MyST) Parser [3] is the recommended replacement.
For the most part, the existing documentation is compatible with MyST,
as both parsers are built around the CommonMark flavor of Markdown. The
main difference that affects coreboot is how the Sphinx toctree is
generated. Recommonmark has a feature called auto_toc_tree, which
converts single level lists of references into a toctree:
* [Part 1: Starting from scratch](part1.md)
* [Part 2: Submitting a patch to coreboot.org](part2.md)
* [Part 3: Writing unit tests](part3.md)
* [Managing local additions](managing_local_additions.md)
* [Flashing firmware](flashing_firmware/index.md)
MyST Parser does not provide a replacement for this feature, meaning the
toctree must be defined manually. This is done using MyST's syntax for
Sphinx directives:
```{toctree}
:maxdepth: 1
Part 1: Starting from scratch <part1.md>
Part 2: Submitting a patch to coreboot.org <part2.md>
Part 3: Writing unit tests <part3.md>
Managing local additions <managing_local_additions.md>
Flashing firmware <flashing_firmware/index.md>
```
Internally, auto_toc_tree essentially converts lists of references into
the Sphinx toctree structure that the MyST syntax above more directly
represents.
The toctrees were converted to the MyST syntax using the following
command and Python script:
`find ./ -iname "*.md" | xargs -n 1 python conv_toctree.py`
```
import re
import sys
in_list = False
f = open(sys.argv[1])
lines = f.readlines()
f.close()
with open(sys.argv[1], "w") as f:
for line in lines:
match = re.match(r"^[-*+] \[(.*)\]\((.*)\)$", line)
if match is not None:
if not in_list:
in_list = True
f.write("```{toctree}\n")
f.write(":maxdepth: 1\n\n")
f.write(match.group(1) + " <" + match.group(2) + ">\n")
else:
if in_list:
f.write("```\n")
f.write(line)
in_list = False
if in_list:
f.write("```\n")
```
While this does add a little more work for creating the toctree, this
does give more control over exactly what goes into the toctree. For
instance, lists of links to external resources currently end up in the
toctree, but we may want to limit it to pages within coreboot.
This change does break rendering and navigation of the documentation in
applications that can render Markdown, such as Okular, Gitiles, or the
GitHub mirror. Assuming the docs are mainly intended to be viewed after
being rendered to doc.coreboot.org, this is probably not an issue in
practice.
Another difference is that MyST natively supports Markdown tables,
whereas with Recommonmark, tables had to be written in embedded rST [4].
However, MyST also supports embedded rST, so the existing tables can be
easily converted as the syntax is nearly identical.
These were converted using
`find ./ -iname "*.md" | xargs -n 1 sed -i "s/eval_rst/{eval-rst}/"`
Makefile.sphinx and conf.py were regenerated from scratch by running
`sphinx-quickstart` using the updated version of Sphinx, which removes a
lot of old commented out boilerplate. Any relevant changes coreboot had
made on top of the previous autogenerated versions of these files were
ported over to the newly generated file.
From some initial testing the generated webpages appear and function
identically to the existing documentation built with Recommonmark.
TEST: `make -C util/docker docker-build-docs` builds the documentation
successfully and the generated output renders properly when viewed in
a web browser.
[1] https://github.com/readthedocs/recommonmark/issues/221
[2] https://pypi.org/project/recommonmark/
[3] https://myst-parser.readthedocs.io/en/latest/
[4] https://doc.coreboot.org/getting_started/writing_documentation.html
Change-Id: I0837c1722fa56d25c9441ea218e943d8f3d9b804
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/73158
Reviewed-by: Matt DeVillier <matt.devillier@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Upstream reimplemented KCONFIG_STRICT, just calling it KCONFIG_WERROR.
Therefore, adapt our build system and documentation. Upstream is less
strict at this time, but there's a proposed patch that got imported.
TEST=`util/abuild/abuild -C` output (config.h and
config.build) remains the same. Also, the failure type fixed in
https://review.coreboot.org/c/coreboot/+/11272 can be detected,
which I tested by manually breaking our Kconfig in a similar way.
Change-Id: I322fb08a2f7308b93cff71a5dd4136f1a998773b
Signed-off-by: Patrick Georgi <patrick@coreboot.org>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/79259
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Martin L Roth <gaumless@gmail.com>
Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
A spelling mistake in the markdown reference to the coreboot vs EDK II
bootflow diagram was previously fixed, but the actual filename was not
changed resulting in a broken reference.
Change-Id: I512646e9af312ba2e1db8f597f6fffa8d54a3515
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/67782
Reviewed-by: Elyes Haouas <ehaouas@noos.fr>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Singer <felixsinger@posteo.net>
Move the devicetree driver example into a separate page under the
drivers category, and link to it from both the devicetree page and
the drivers index page. This makes more sense from a grouping
perspective and makes the info easier to find.
Change-Id: Ic3ca80b93a0020737c7ccb5313a0877172022e1a
Signed-off-by: Matt DeVillier <matt.devillier@amd.corp-partner.google.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/67762
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Break TPM related Kconfig into the following dimensions:
TPM transport support:
config CRB_TPM
config I2C_TPM
config SPI_TPM
config MEMORY_MAPPED_TPM (new)
TPM brand, not defining any of these is valid, and result in "generic" support:
config TPM_ATMEL (new)
config TPM_GOOGLE (new)
config TPM_GOOGLE_CR50 (new, implies TPM_GOOGLE)
config TPM_GOOGLE_TI50 (new to be used later, implies TPM_GOOGLE)
What protocol the TPM chip supports:
config MAINBOARD_HAS_TPM1
config MAINBOARD_HAS_TPM2
What the user chooses to compile (restricted by the above):
config NO_TPM
config TPM1
config TPM2
The following Kconfigs will be replaced as indicated:
config TPM_CR50 -> TPM_GOOGLE
config MAINBOARD_HAS_CRB_TPM -> CRB_TPM
config MAINBOARD_HAS_I2C_TPM_ATMEL -> I2C_TPM && TPM_ATMEL
config MAINBOARD_HAS_I2C_TPM_CR50 -> I2C_TPM && TPM_GOOGLE
config MAINBOARD_HAS_I2C_TPM_GENERIC -> I2C_TPM && !TPM_GOOGLE && !TPM_ATMEL
config MAINBOARD_HAS_LPC_TPM -> MEMORY_MAPPED_TPM
config MAINBOARD_HAS_SPI_TPM -> SPI_TPM && !TPM_GOOGLE && !TPM_ATMEL
config MAINBOARD_HAS_SPI_TPM_CR50 -> SPI_TPM && TPM_GOOGLE
Signed-off-by: Jes B. Klinke <jbk@chromium.org>
Change-Id: I4656b2b90363b8dfd008dc281ad591862fe2cc9e
Reviewed-on: https://review.coreboot.org/c/coreboot/+/63424
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Yu-Ping Wu <yupingso@google.com>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Reviewed-by: Julius Werner <jwerner@chromium.org>
Nicholas Chin
Martin Roth
Nicolas Kochlowski
Pablo Iranzo Gómez
Felix Singer
Patrick Georgi
Simon Glass
Marshall Dawson
Matt DeVillier
Marc Jones
Jes B. Klinke
Subrata Banik