From 35599f9a6671779a377443ae6e596367a7613e22 Mon Sep 17 00:00:00 2001 From: Nicholas Chin Date: Tue, 21 Feb 2023 19:41:06 -0700 Subject: Docs: Replace Recommonmark with MyST Parser 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 Part 2: Submitting a patch to coreboot.org Part 3: Writing unit tests Managing local additions Flashing firmware ``` 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 Reviewed-on: https://review.coreboot.org/c/coreboot/+/73158 Reviewed-by: Matt DeVillier Tested-by: build bot (Jenkins) --- Documentation/tutorial/flashing_firmware/index.md | 28 ++++++++++++++++------- Documentation/tutorial/index.md | 14 ++++++++---- Documentation/tutorial/part3.md | 26 ++++++++++----------- 3 files changed, 42 insertions(+), 26 deletions(-) (limited to 'Documentation/tutorial') diff --git a/Documentation/tutorial/flashing_firmware/index.md b/Documentation/tutorial/flashing_firmware/index.md index da3d7f098f..3063e4c3dd 100644 --- a/Documentation/tutorial/flashing_firmware/index.md +++ b/Documentation/tutorial/flashing_firmware/index.md @@ -7,10 +7,14 @@ flash IC. ## Contents -* [Flashing internally](int_flashrom.md) -* [Flashing firmware standalone](ext_standalone.md) -* [Flashing firmware externally supplying direct power](ext_power.md) -* [Flashing firmware externally without supplying direct power](no_ext_power.md) +```{toctree} +:maxdepth: 1 + +Flashing internally +Flashing firmware standalone +Flashing firmware externally supplying direct power +Flashing firmware externally without supplying direct power +``` ## General advice @@ -43,7 +47,11 @@ There are multiple ways to update the firmware: * A UEFI firmware update capsule More details on flashrom's -* [internal programmer](int_flashrom.md) +```{toctree} +:maxdepth: 1 + +internal programmer +``` ## External method @@ -56,9 +64,13 @@ Please also have a look at the mainboard-specific documentation for details. After exposing the firmware flash IC, read the schematics and use one of the possible methods: -* [Flashing firmware standalone](ext_standalone.md) -* [Flashing firmware externally supplying direct power](ext_power.md) -* [Flashing firmware externally without supplying direct power](no_ext_power.md) +```{toctree} +:maxdepth: 1 + +Flashing firmware standalone +Flashing firmware externally supplying direct power +Flashing firmware externally without supplying direct power +``` **WARNING:** Using the wrong method or accidentally using the wrong pinout might permanently damage your hardware! diff --git a/Documentation/tutorial/index.md b/Documentation/tutorial/index.md index 384f84084e..e5923703d6 100644 --- a/Documentation/tutorial/index.md +++ b/Documentation/tutorial/index.md @@ -1,7 +1,11 @@ # Tutorial -* [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) +```{toctree} +:maxdepth: 1 + +Part 1: Starting from scratch +Part 2: Submitting a patch to coreboot.org +Part 3: Writing unit tests +Managing local additions +Flashing firmware +``` diff --git a/Documentation/tutorial/part3.md b/Documentation/tutorial/part3.md index ec49637e29..377782c03c 100644 --- a/Documentation/tutorial/part3.md +++ b/Documentation/tutorial/part3.md @@ -28,7 +28,7 @@ First of all, it is necessary to precisely establish what we want to test in a particular module. Usually this will be an externally exposed API, which can be used by other modules. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example In case of our UUT, API consist of two methods: @@ -49,7 +49,7 @@ Once the API is defined, the next question is __what__ this API is doing we are expecting from particular functions, when providing particular input parameters. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example .. code-block:: c @@ -71,7 +71,7 @@ thus should be simply linked into the test binaries, all hardware dependencies need to be mocked out, since in the user-space host environment, target hardware is not available. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example `i2c_read_field` is calling `i2c_readb`, which eventually invokes @@ -88,7 +88,7 @@ In order to keep the tree clean, the `tests/` directory should mimic the corresponding to UUT. Furthermore, the naming convention is to add the suffix `-test` to the UUT name when creating a new test harness file. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example Considering that UUT is `src/device/i2c.c`, test file should be named @@ -100,7 +100,7 @@ Every directory under `tests/` should contain a Makefile.mk, similar to what can be seen under the `src/`. Register a new test in Makefile.mk, by __appending__ test name to the `tests-y` variable. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example .. code-block:: c @@ -114,7 +114,7 @@ in order to create test binary. Usually a tests requires only two files test environment. Source files are registered in `-srcs` variable. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example .. code-block:: c @@ -128,7 +128,7 @@ build and run test binary either by invoking `make tests//` or by running all unit tests (whole suite) for coreboot `make unit-tests`. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example .. code-block:: c @@ -164,7 +164,7 @@ macros](https://api.cmocka.org/group__cmocka__asserts.html) to compare a value with an expected value. If the two values do not match, the test fails with an error message. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example In our example, the simplest test is to call UUT for reading our fake @@ -215,7 +215,7 @@ being mocked. Such a mock may, for example, register a set of driver methods. Behind this API, there is usually a simulation of real hardware. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example For purpose of our i2c test, we may introduce two i2c devices with @@ -289,7 +289,7 @@ mocked into -mocks variable in Makefile.mk. The result is that the test's implementation of that function is called instead of coreboot's. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example .. code-block:: c @@ -320,7 +320,7 @@ the corresponding test function, `expect*()` macro, with description which parameter in which mock should have particular value, or be inside a described range. -```eval_rst +```{eval-rst} .. admonition:: i2c-test example In our example, we may want to check that `platform_i2c_transfer` is @@ -366,7 +366,7 @@ return to the UUT. This can be done by using the `will_return*()` and section](https://api.cmocka.org/group__cmocka__mock.html) of the Cmocka API documentation. -```eval_rst +```{eval-rst} .. admonition:: Example There is an non-coreboot example for using Cmocka available @@ -379,7 +379,7 @@ All tests should be registered there and the cmocka test runner invoked. All methods for invoking Cmocka test are described [here](https://api.cmocka.org/group__cmocka__exec.html). -```eval_rst +```{eval-rst} .. admonition:: i2c-test example We don't need any extra setup and teardown functions for i2c-test, so -- cgit v1.2.3