| Age | Commit message (Collapse) | Author |
|---|
|
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>
|
|
The options in conf.py for the following build targets are either
commented out or contain example values, which suggests that there was
no interest in them recently. Their comments also seem more like
generated examples.
* LaTeX
* man pages
* Texinfo
In order to clean up our configs and scripts for the documentation,
remove the configuration options from conf.py for these build targets.
Also, remove the build targets responsible for generating a PDF file
from Makefile. Don't touch Makefile.sphinx for now though as we usually
wrap around it.
We may bring these build targets back if there is real interest in
them, but it seems only the HTML target was really used.
Change-Id: I7df8ea886f94d9b25e8eeb0ccbc2a7392b96a575
Signed-off-by: Felix Singer <felixsinger@posteo.net>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/77439
Reviewed-by: Martin L Roth <gaumless@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
|
|
Newer versions of Sphinx complain about the language being set to None,
so explicitly set it to 'en'. The syntax that is currently used to
enable custom CSS styling for tables [1] also no longer works, resulting
in the docs rendering without CSS. Fix this using the html_css_files
option instead.
TEST: The documentation builds and renders correctly with both Sphinx
1.8.3 in from the doc.coreboot.org Docker container and Sphinx 7.2.2
from distro packages.
[1] Commit a78e66e5f4: Documentation: Add static CSS file to fix tables
Change-Id: I036b1cad3cfa533c0c3a037bac649caa2d968d4b
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/75466
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
|
|
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>
|
|
Without the brackets, the string seems to be added as a list of
characters, and since there's no extension called 's', sphinx
bails out.
Change-Id: If0fc9c1a74f334b6154df3cb26836509de913567
Signed-off-by: Patrick Georgi <pgeorgi@google.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/44114
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
|
|
* Add support for Sphinx 3.0+
* Add backward support for Sphinx 1.8 and older
* Make sphinxcontrib ditaa an optional extension
* Allow SPHINXOPTS to be set from command line
* Add sphinx and sphinx-lint to top level Makefile
Change-Id: If10aef51dc426445cb742aad13b19ee7fe169c51
Signed-off-by: Patrick Rudolph <siro@das-labor.org>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/41492
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
|
|
For prettier diagrams: http://ditaa.sourceforge.net/
Change-Id: Ic28dc5ea9d82ff6bf8654e2e33e675a536348654
Signed-off-by: Patrick Georgi <pgeorgi@google.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/37646
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net>
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
|
|
recommonmark doesn't know about inline code, while all other software generating
documentation is able to handle it.
Add support for inline code by adding a wrapper class around the recommonmark
parser that converts code to docutils literal blocks.
Fixes invisible inline code in current documentation.
Change-Id: I0269d15a685ed0c0241be8c8acfade0e58363845
Signed-off-by: Patrick Rudolph <siro@das-labor.org>
Reviewed-on: https://review.coreboot.org/29206
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net>
Reviewed-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
|
|
According to recommonmark's documentation the enable_auto_doc_ref is deprecated.
This is not true, as it's broken with Sphinx 1.6+ commit
12d639873953847de31ec99742b42e50e89ed58c.
recommonmark bug report is here: https://github.com/rtfd/recommonmark/issues/73
Instead of using this feature, which doesn't support top level directories in
the relative document path anyway, use the TOC tree or inline RST code.
Disable auto_doc_ref and document how to reference documents.
Change-Id: I9319985b504c4215c33ebbeb9c38317b9efcb283
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/28550
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Tom Hiller <thrilleratplay@gmail.com>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
|
|
With python3 the split method can operate on strings while check_output
generates bytestrings.
Change-Id: I7b455c56e8195f0ecfbe5e360ac161c176f00115
Signed-off-by: Arthur Heymans <arthur@aheymans.xyz>
Reviewed-on: https://review.coreboot.org/27630
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
|
|
Change-Id: I79cceca7373f8bdf9bbfba5d84b8fa589afa838b
Signed-off-by: Patrick Georgi <patrick@georgi.software>
Reviewed-on: https://review.coreboot.org/26897
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
|
|
Change-Id: I8cb5b122162c40435f93019c9be9a367d2656cf1
Signed-off-by: Elyes HAOUAS <ehaouas@noos.fr>
Reviewed-on: https://review.coreboot.org/26660
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
|
|
Add CC-by 4.0 license written in markdown and add global copyright string.
Change-Id: I31dc540d63b289d38d6d7d9a7c35b6bb50f9c92d
Signed-off-by: Patrick Rudolph <siro@das-labor.org>
Reviewed-on: https://review.coreboot.org/26264
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Martin Roth <martinroth@google.com>
|
|
Add a static CSS file to remove annoying scrollbars on rst code tables.
Change-Id: I436b36fb7ee9856c7d6ad8534cd0610b7f071b17
Signed-off-by: Patrick Rudolph <siro@das-labor.org>
Reviewed-on: https://review.coreboot.org/26263
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
|
|
* This feature embedds RST into markdown for
table generation.
For more information, see
http://recommonmark.readthedocs.io/en/latest/index.html#autostructify
Change-Id: Iefebb3b7857bc98818e345f7d0e95fbf987305a8
Signed-off-by: Philipp Deppenwiese <zaolin@das-labor.org>
Reviewed-on: https://review.coreboot.org/26190
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
|
|
This commit adds the necessary infrastructure to convert the Markdown
files in the Documentation directory to HTML using Sphinx[1] and
recommonmark[2]. I selected "sphinx_rtd_theme" as the theme, because it
offers a useful navigation sidebar, and because it's already used for
the Linux kernel[3].
Makefile.sphinx was auto-generated by sphinx-quickstart. conf.py was
auto-generated and manually adjusted.
[1]: http://www.sphinx-doc.org/en/stable/
[2]: https://recommonmark.readthedocs.io/en/latest/
[3]: https://www.kernel.org/doc/html/latest/index.html
Change-Id: Ie4de96978e334c598cf5890775807d3e15c29c4d
Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Reviewed-on: https://review.coreboot.org/25787
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
|
