summaryrefslogtreecommitdiff
path: root/Documentation/community
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>
2023-08-08doc/forums: Update Matrix channel linkNico Huber
Channel portalling has been disabled for the matrix.org-libera.chat bridge[1]. Hence, we created a new Matrix channel #coreboot:matrix.org (that is plumbed to the IRC channel). [1] https://libera.chat/news/matrix-deportalling Change-Id: I896bfed71790988503dc8229fe9b34e175046dbf Signed-off-by: Nico Huber <nico.h@gmx.de> Reviewed-on: https://review.coreboot.org/c/coreboot/+/76864 Reviewed-by: Paul Menzel <paulepanter@mailbox.org> Reviewed-by: Patrick Georgi <patrick@coreboot.org> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2023-08-07Documentation: Add section on how the project responds to legal threatsPatrick Georgi
Threatening or initiating legal action against the maintainers of our infrastructure or projects (all projects hosted on our infrastructure) is a huge stressor to those maintainers. To underline that severity, such threats or action will lead to an immediate ban from our infrastructure as agreed on the leadership meeting of 2023-05-31. There may be legitimate legal action to take in certain cases, and it's always possible to unban people, but given the severity provide warning that we'll opt for a "ban first, sort out later" approach. Change-Id: Ifa865487dc81ed3797fe60e5cef737c57dd85fea Signed-off-by: Patrick Georgi <patrick@coreboot.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/75554 Reviewed-by: Elyes Haouas <ehaouas@noos.fr> Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
2022-09-09Documentation/community: Update leadership meeting linkNicholas Chin
Update the Google Meet link to match the one found in the meeting agenda and the reminders sent on the various community forums. Change-Id: Ic4b8e0bb01e57850ea199c62b66a16e4d14de5c5 Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/67459 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Patrick Georgi <patrick@coreboot.org>
2022-04-24Documentation: Move services page to infrastructure sectionFelix Singer
The services page documents various services and tools which are provided by the project. It's more related to the infrastructure and less related to the community section. Thus, move it to the infrastructure section. Change-Id: I0ca2aba8ae817cf874367fa17e567065aec99a93 Signed-off-by: Felix Singer <felixsinger@posteo.net> Reviewed-on: https://review.coreboot.org/c/coreboot/+/62442 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Martin L Roth <martinroth@google.com> Reviewed-by: Paul Menzel <paulepanter@mailbox.org>
2022-03-14Documentation: Fix broken linksMartin Roth
This change mostly changes links that were identified as broken by the 'website_scans' jenkins job. There were some links that seem to be up at times, but that are identified by link-checker as broken because of SSL issues. At least one other link was changed to point to archive.org so that it doesn't break at some point in the future. We should probably try to make sure that everything is archived there and point to those versions when possible. There are still lots more links to do. Signed-off-by: Martin Roth <martin@coreboot.org> Change-Id: I36868ddf6113e18fa6841427dd635c75445b7bef Reviewed-on: https://review.coreboot.org/c/coreboot/+/62672 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Singer <felixsinger@posteo.net>
2022-02-25Documentation/index.md: Add "Community" menu entryFelix Singer
Clean up the main menu by adding a new entry `Community` and moving all related menu entries below it. Change-Id: Ib5df0156edaa739f15e6da8489968448876e1894 Signed-off-by: Felix Singer <felixsinger@posteo.net> Reviewed-on: https://review.coreboot.org/c/coreboot/+/62219 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@mailbox.org> Reviewed-by: Arthur Heymans <arthur@aheymans.xyz> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
2022-02-23Documentation/community/services: Fix typoFelix Singer
Change-Id: I9d5171bd115d676775f560306e4e0a86214a39b0 Signed-off-by: Felix Singer <felixsinger@posteo.net> Reviewed-on: https://review.coreboot.org/c/coreboot/+/62218 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@mailbox.org> Reviewed-by: Elyes Haouas <ehaouas@noos.fr> Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
2021-10-08Documentation: Explain how to join SlackPatrick Georgi
Change-Id: I6a4d5011ea47576c9a459f20e0b368cff8a326c2 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/58150 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Paul Menzel <paulepanter@mailbox.org>
2021-06-01Documentation/community: Add link to the OSF SlackArthur Heymans
We are also present on Slack so advertise that. Change-Id: I7d9887e524e47e6f42a5013e9f696881ef54a631 Signed-off-by: Arthur Heymans <arthur@aheymans.xyz> Reviewed-on: https://review.coreboot.org/c/coreboot/+/55036 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Georgi <pgeorgi@google.com>
2021-06-01Documentation/community: Add Discord to forumsPatrick Georgi
Change-Id: Ib1d866ecf041ddc4aaf508d290a3e31b9a108cf2 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/55018 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
2021-05-28Documentation: Update real time chat optionsPatrick Georgi
Change-Id: I3035266c5e035b954c0d709bd2c09069128c3340 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/55010 Reviewed-by: Felix Singer <felixsinger@posteo.net> Reviewed-by: Swift Geek (Sebastian Grzywna) <swiftgeek@gmail.com> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Felix Held <felix-coreboot@felixheld.de> Reviewed-by: Michael Niewöhner <foss@mniewoehner.de> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2021-04-15Documentation: List the leadership meeting as one of our forumsPatrick Georgi
Change-Id: I00822cc631c5451862bd94683ff45289ecc75679 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/52264 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Jan Dabros <jsd@semihalf.com>
2020-08-31Documentation: Discuss how we use languagePatrick Georgi
Change-Id: I44fa30af538c78760821401c8d3c52029d95b72b Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/43420 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Werner Zeh <werner.zeh@siemens.com> Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
2019-10-07Documentation: Add our issue tracker to servicesPatrick Georgi
Change-Id: Ib249d5c6f2431336a01850f4a8d708795983e7d3 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/35806 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Rudolph <siro@das-labor.org>
2019-10-07Documentation: start documenting our servicesPatrick Georgi
Change-Id: I4d687d13e8d47e3e3e6f319b9117d3c4f31caa78 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/35805 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Rudolph <siro@das-labor.org>
2019-07-19Documentation/code_of_conduct: Update arbitration teamPatrick Georgi
Marc found more interesting things to do (yay, Marc!) and Martin offered to volunteer on the arbitration board in his place. Change-Id: Ic5bf00735afdf8942e543043238890011a82c890 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/34392 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Werner Zeh <werner.zeh@siemens.com> Reviewed-by: Kyösti Mälkki <kyosti.malkki@gmail.com>
2019-07-19Documentation/code_of_conduct: Emphasize definition of community org.Patrick Georgi
The paragraph starts talking about community organizers. By making their definition a separate paragraph it's hopefully easier to find what this means. Change-Id: Icb9abbbd05b59bd4ee741d10f4c9c1a8c321b430 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/34391 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Werner Zeh <werner.zeh@siemens.com> Reviewed-by: Kyösti Mälkki <kyosti.malkki@gmail.com>
2019-07-19Documentation/code_of_conduct: Highlight the reporting processPatrick Georgi
Make it a separate section, emphasize that people should get support early, note that personal interaction and email are the two best ways to seek help. Change-Id: I8cb613fefe1a7b4db1ee948fb9927a38f0421011 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/34390 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Werner Zeh <werner.zeh@siemens.com> Reviewed-by: Kyösti Mälkki <kyosti.malkki@gmail.com> Reviewed-by: Martin Roth <martinroth@google.com>
2019-07-19Documentation/code_of_conduct: Assume the best as long as you canPatrick Georgi
"Always assume" is rather final and (in some readings) invalidates the need for the rest of the text. Change-Id: Ibf6f776494367d012ce69a64fa928c1dd4206c0e Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/34389 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Werner Zeh <werner.zeh@siemens.com> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Kyösti Mälkki <kyosti.malkki@gmail.com>
2019-02-19Documentation: Add past talks to conferences pagePatrick Georgi
Change-Id: I2b8a0ebda3c8fa7d1777a6f0628fd99d73a0d341 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/31451 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net>
2019-02-11Documentation: remove the upcoming events chapter from the conferences pageMartin Kepplinger
I think our docs inside of the codebase might not be the ideal place to announce future events. First, they might be scheduled so shortly before the conference that the change, if at all done, would barely make it to the repo and the web. Also, _if_ really maintained, it would churn the docs unnessesarily. But, I doubt that anyone of us would want to maintain this here at all. Lastly, I think that nobody out there would _look for_ upcoming events in coreboot's documentation. We have bigger problems in the Documentation directory than this :) Change-Id: I918e17a427405a05722c6e0d61dc422f94cac809 Signed-off-by: Martin Kepplinger <martink@posteo.de> Reviewed-on: https://review.coreboot.org/c/31266 Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2019-02-11Documentation: add the most recent talks to the conferences pageMartin Kepplinger
Add Philipps great 35c3 talk and Davids and Andreas fosdem talk to the conferences page. linuxboot adds those to their website too but they can't be linked to too often :) Change-Id: I1e7ce078020dc5e9c9d9d47210c70ee16ef2f82e Signed-off-by: Martin Kepplinger <martink@posteo.de> Reviewed-on: https://review.coreboot.org/c/31265 Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2019-01-30Documentation: Add some description of our communal placesPatrick Georgi
Change-Id: Iede98359c22aefbfd5725a5e7cd661ef18d7284e Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/31146 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-14 22:38:17 +0000