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 <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>

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 <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>
+```
 
 ## 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 <int_flashrom.md>
+```
 
 ## 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 <ext_standalone.md>
+Flashing firmware externally supplying direct power <ext_power.md>
+Flashing firmware externally without supplying direct power <no_ext_power.md>
+```
 
 **WARNING:** Using the wrong method or accidentally using the wrong pinout might
   permanently damage your hardware!

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 <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>
+```

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 `<test_name>-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/<test_dir>/<test_name>` 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 <test_name>-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