Attention is currently required from: Nico Huber.
Nicholas Chin has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/81503?usp=email )
Change subject: doc/getting_started: Update embedded-table examples ......................................................................
Patch Set 2:
(2 comments)
Patchset:
PS1:
Ok, so then let's keep it simple and keep suggesting to use rST tables?
I think that's reasonable, as it keeps everything consistent. Though I think some people might appreciate having the option to use markdown syntax.
File Documentation/getting_started/writing_documentation.md:
https://review.coreboot.org/c/coreboot/+/81503/comment/38328c9d_f092894d : PS2, Line 147: ```{eval-rst} : .. csv-table:: : :header: "Key", "Value" : :file: keyvalues.csv : ``` This should work, as the contents of an eval-rst block just needs to be valid reST, which doesn't depend on Recommonmark vs MyST. However, MyST also provides more direct integration of Sphinx directives allowing it to call csv-table without enclosing it in an eval-rst block: https://myst-parser.readthedocs.io/en/latest/syntax/tables.html#csv-tables
That does make the docs more MyST specific though instead of Markdown + standard reST + minimal implementation specific bridging syntax (`{eval-rst}`), so I'm not sure if it's really worth switching. However, there are other areas where the direct Sphinx directives might be nice, such as using the `:doc:` directive. For example, `northbridge/intel/haswell/known-issues.md` encloses an entire paragraph in `{eval-rst}` just to use that, whereas with the direct syntax, eval-rst isn't needed and `{doc}` can be used directly in place of `:doc:`.
-
Nicholas Chin (Code Review)