summaryrefslogtreecommitdiff
path: root/Documentation/conf.py
AgeCommit message (Collapse)Author
2024-08-25Docs/conf.py: Explicitly define external URL schemesNicholas Chin
By default, any URL with a scheme of "http", "https", "ftp", or "mailto" is treated as an external link. Since the "ircs" scheme is not included, the IRC link in community/forums.md does not get resolved as an external link, and instead tries to link to a header in the docs themselves. Fix this by explicitly defining which schemes should resolve to external links using the myst_url_schemes configuration option [1], which is now set to the default schemes along with "ircs". This fixes the "cross-reference target not found" warning for 'ircs://irc.libera.chat/#coreboot' [1] https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#customising-external-url-resolution Change-Id: I9e1c76b2bacbacaa06340f940c76b50de38e43e8 Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/84069 Reviewed-by: Nico Huber <nico.h@gmx.de> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
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>
2023-09-21Documentation: Remove unused build targetsFelix Singer
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>
2023-08-20Documentation: Fix conf.py for newer Sphinx versionsNicholas Chin
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>
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>
2020-08-04Documentation: Fix sphinx configurationPatrick Georgi
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>
2020-07-01Documentation: Add several fixesPatrick Rudolph
* 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>
2019-12-12Documentation: enable ditaa integrationPatrick Georgi
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>
2018-10-22Documentation: Fix markdown inline codePatrick Rudolph
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>
2018-09-30Documentation: Disable auto_doc_refTom Hiller
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>
2018-07-26Documenation/conf.py: Make sure release is a stringArthur Heymans
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>
2018-06-07Documentation: inject the current git revision into the websitePatrick Georgi
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>
2018-06-04Documentation: Remove whitespace before tabElyes HAOUAS
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>
2018-06-04Documentation: Add markdown license informationPatrick Rudolph
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>
2018-05-14Documentation: Add static CSS file to fix tablesPatrick Rudolph
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>
2018-05-11Dokumentation: Sphinx add RST in markdown supportPhilipp Deppenwiese
* 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>
2018-04-26Documentation: Add support for building with SphinxJonathan Neuschäfer
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>
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-14 06:23:43 +0000