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>
This tool doesn't have a makefile, when trying to compile it manually
with the given instructions it even fails to compile after fixing the
paths in the given command, and it references the non-existing
PCI_BUS_SEGN_BITS Kconfig symbol, so just drop this.
Signed-off-by: Felix Held <felix-coreboot@felixheld.de>
Change-Id: I8ca75db281a215bf3f194ab72a107f666dc0694e
Reviewed-on: https://review.coreboot.org/c/coreboot/+/79934
Reviewed-by: Martin Roth <martin.roth@amd.corp-partner.google.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Add new documentation generated by util/util_readme/util_readme.sh.
This also fixes the following Sphinx warning:
util/abuild/index.md: WARNING: document isn't included in any toctree
Change-Id: I26c33af3c5a5853f6bcce23e982a6b192b01f1d7
Signed-off-by: Felix Singer <felixsinger@posteo.net>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/77441
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Nicholas Chin <nic.c3.14@gmail.com>
The description.md file for the intelp2m utility wasn't the description
that was needed - just a subject, and what language it was written in.
It was instead a set of more full documentation, so move it into the
Documentation directory and create a new description file.
Change-Id: Ia180ae41f91f8b8eb408351a9e44e899edc031d3
Signed-off-by: Martin Roth <gaumless@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/64578
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Singer <felixsinger@posteo.net>
apcb_v3_edit.py tool edits APCB V3 binaries. Specifically it will inject
up to 16 SPDs into an existing APCB. The APCB must have a magic number
at the top of each SPD slot.
BUG=b:209486191
BRANCH=None
TEST=Inject 4 SPDs into magic APCB, boot guybrush with modified APCB
Change-Id: I9148977c415df41210a3a13a1cd9b3bc1504a480
Signed-off-by: Rob Barnes <robbarnes@google.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/60281
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Raul Rangel <rrangel@chromium.org>
This change adds details memory mapped window handling in cbfstool
required for x86 platforms. It also captures the details about the
newly added support for multiple decode windows.
BUG=b:171534504
Change-Id: Icf970f951e56d717e6a4f8845fc73f10d5a21dd0
Signed-off-by: Furquan Shaikh <furquan@google.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/48477
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Reviewed-by: Duncan Laurie <dlaurie@chromium.org>
Add an option to ifdtool which validates that the flash regions defined
in the descriptor match the coresponding areas in the FMAP.
BUG=chromium:992215
TEST=Ran 'ifdtool -t' with a good bios image and verify no issues
run 'ifdtool -t' with a bad bios image and verify expected issues
Signed-off-by: Mathew King <mathewk@chromium.org>
Change-Id: Idebf105dee1b8f829d54bd65c82867af7aa4aded
Reviewed-on: https://review.coreboot.org/c/coreboot/+/34802
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
Carl-Daniel made this script a long time ago but it never was picked up
in the tree. Now that USB debugging is way more common it makes
sense to include it.
I have made a number of changes to the original version:
* -h help text
* check for running as root
* enhanced readability (test -> if)
* new execution flow and refined output that better shows the device(s)
attached to the debug port(s)
* handling of Intel rate-matching hubs
* hiding of (bogus) error messages from lspci and lsusb
Signed-off-by: Stefan Tauner <stefan.tauner@gmx.at>
Change-Id: Iadf775e990f5c5f91a28d57e3331d1f59acee305
Reviewed-on: https://review.coreboot.org/c/9305
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
The reason for this code cleanup is the legacy
Google Purin board which isn't available anymore
and AFAIK never made it into the stores.
* Remove broadcom cygnus SoC support
* Remove /util/broadcom tool
* Remove Google Purin mainboard
* Remove MAINTAINERS entries
Change-Id: I148dd7eb0192d396cb69bc26c4062f88a764771a
Signed-off-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
Reviewed-on: https://review.coreboot.org/c/29905
Reviewed-by: Julius Werner <jwerner@chromium.org>
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
