summaryrefslogtreecommitdiff
path: root/Documentation/mainboard/ocp
AgeCommit message (Collapse)Author
2024-03-21Docs: Replace Recommonmark with MyST ParserNicholas Chin
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>
2024-01-04Documentation: Update internal URL'sJon Murphy
Update URL's to point to head rather than the deprecated refs/heads/master. Change-Id: I16f0c087762ff049115b67de3ac0b881aa4e4b40 Signed-off-by: Jon Murphy <jpmurphy@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/79785 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Matt DeVillier <matt.devillier@amd.corp-partner.google.com>
2022-12-22doc/mb/ocp/deltalake: add section on how to work on corebootJonathan Zhang
Update Delta Lake documentation to add some clarification. Add a section on how to work on coreboot for the Delta Lake server. Change-Id: Id756ee0a09cdcd1200752a03e980441db1537ad1 Signed-off-by: Jonzhang Zhang <jonzhang@meta.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/69169 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: David Hendricks <david.hendricks@gmail.com> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
2021-11-18doc/mb/ocp: update Delta Lake documentationJonathan Zhang
Update Delta Lake document following the publish of OCP blog and the Wiwynn press release. Signed-off-by: Jonathan Zhang <jonzhang@fb.com> Change-Id: I3eaa765bf9918988b4b5cb01e8607a5c27b9bd17 Reviewed-on: https://review.coreboot.org/c/coreboot/+/58979 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Johnny Lin <Johnny_Lin@wiwynn.com> Reviewed-by: Christian Walter <christian.walter@9elements.com> Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
2021-10-05Documentation: Fix spelling errorsMartin Roth
These issues were found and fixed by codespell, a useful tool for finding spelling errors. Signed-off-by: Martin Roth <martin@coreboot.org> Change-Id: If2a8e97911420c19e9365d5c28810b998f2c2ac8 Reviewed-on: https://review.coreboot.org/c/coreboot/+/58078 Reviewed-by: Felix Held <felix-coreboot@felixheld.de> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2021-09-23doc/mainboard/ocp: update Delta Lake documentationJonathan Zhang
Update Delta Lake documentation upon: * Delta Lake and Yosemite-V3 design specs acceptance by OCP. * Delta Lake OSF acceptance by OCP. Signed-off-by: Jonathan Zhang <jonzhang@fb.com> Change-Id: I315db879b75f0df2fbca2fa8bb6d00987a69efba Reviewed-on: https://review.coreboot.org/c/coreboot/+/57688 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Christian Walter <christian.walter@9elements.com>
2021-09-09intel/xeon_sp/cpx: Hook up public microcode releaseArthur Heymans
Change-Id: I7e575cb17e2004bd931f4fa1d05f17c4cdca29ba Signed-off-by: Arthur Heymans <arthur@aheymans.xyz> Reviewed-on: https://review.coreboot.org/c/coreboot/+/57444 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Jonathan Zhang <jonzhang@fb.com> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
2021-09-01Doc/mb/ocp: Add hyperlink to src/mainboard/ocp/deltalake/vpd.hJohnny Lin
It would be easier for people to find the defined variables. Change-Id: I6d181f6602aa5d55019ea2110b2d8e1fa7e0159c Signed-off-by: Johnny Lin <johnny_lin@wiwynn.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/57255 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Jonathan Zhang <jonzhang@fb.com>
2021-08-27Doc/mb/ocp: Update Delta Lake documentation for RAS featuresJohnny Lin
Change-Id: I71b97930f1a1ca4a60f830a90d80af6ca0236c8e Signed-off-by: Johnny Lin <johnny_lin@wiwynn.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/57093 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Jonathan Zhang <jonzhang@fb.com>
2021-04-15Documentation/mb/ocp: Update Delta Lake documentationJonathan Zhang
Update OCP Delta Lake documentation following OSF (Open System Firmware) solution reaching DVT exit parity. This alternative host firmware solution uses FSP/coreboot/Linuxboot stack. Signed-off-by: Jonathan Zhang <jonzhang@fb.com> Change-Id: Ifd6ab251cd7806cf8cd3f984ad88c091f85035cf Reviewed-on: https://review.coreboot.org/c/coreboot/+/51824 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Sumeet R Pawnikar <sumeet.r.pawnikar@intel.com> Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
2021-02-24doc/mb/ocp: Update DeltaLake for VPD variables used in LinuxBootJohnny Lin
u-root commits: bmc_bootorder_override https://github.com/u-root/u-root/pull/1902 systemboot_log_level: https://github.com/u-root/u-root/pull/1922 Change-Id: I3da7291188ee06c50008aa3fc7142210215044d4 Signed-off-by: Johnny Lin <johnny_lin@wiwynn.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/50377 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Marc Jones <marc@marcjonesconsulting.com>
2020-12-05Documentation/mainboard/ocp: Update DeltaLakeJonathan Zhang
DeltaLake Open System Firmware stack (FSP/coreboot/Linuxboot) has reached EVT exit parity. Update the documentation accordingly. Signed-off-by: Jonathan Zhang <jonzhang@fb.com> Change-Id: I7cce855d207a53b1d3cd497b74cdc0b00027a3ce Reviewed-on: https://review.coreboot.org/c/coreboot/+/48252 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Christian Walter <christian.walter@9elements.com>
2020-09-28doc/mb/ocp: update deltalake server documentationJonathan Zhang
Upon completion of 2nd build/test/release cycle of Deltalake server alternative firmware engineering, update the document. Signed-off-by: Jonathan Zhang <jonzhang@fb.com> Change-Id: I1806526bd477ed407bb7fd36c7fe4ce0e57b72f0 Reviewed-on: https://review.coreboot.org/c/coreboot/+/45707 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Georgi <pgeorgi@google.com>
2020-08-14doc/mb/ocp: update Delta Lake documentationJonathan Zhang
Update Delta Lake documentation following ww30 to ww33 build/test/release cycle. Signed-off-by: Jonathan Zhang <jonzhang@fb.com> Change-Id: I9bb3a4daa423503d487045f2f069a43d2cc09129 Reviewed-on: https://review.coreboot.org/c/coreboot/+/44360 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
2020-07-04doc/mb/ocp: Add documentation for Delta LakeJonathan Zhang
Add OCP platform Delta Lake documentation. Signed-off-by: Jonathan Zhang <jonzhang@fb.com> Change-Id: I9216c80023db071591c8d3add7c0f041e9e6b97e Reviewed-on: https://review.coreboot.org/c/coreboot/+/42947 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Christian Walter <christian.walter@9elements.com> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
2020-06-22Doc/mb/ocp: Add documentation for Tioga PassJonathan Zhang
Add OCP platform Tioga Pass documentation. Signed-off-by: Jonathan Zhang <jonzhang@fb.com> Signed-off-by: Reddy Chagam <anjaneya.chagam@intel.com> Change-Id: If4c2832d5bd006c572dab035040b4242f8a3d53b Reviewed-on: https://review.coreboot.org/c/coreboot/+/40925 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-02 10:31:11 +0000