1619381 - fix tables in Markdown documentation

Status: RESOLVED FIXED

(Firefox :: Messaging System, task, P1)

Description

[Dan Mosedale (:dmose, :dmosedale)]

Our Markdown documentation has a number of files with tables in them (eg data_dictionary.md). The markdown parser used by mach doc doesn't support tables, so they currently show up broken on firefox-source-docs.mozilla.org.

The workaround for people who to view them currently is simply to give them a link to the source files in searchfox, but that's awfully ugly.

It would be nice if they rendered correctly. I've set this to currently depend on another bug which swaps out recommonmark in mach doc for a fork called sphinx-markdown-parser. However, if that turns out to be too much work, we could try another strategy, eg using eval_rst to embed rst tables in the Markdown or converting the tables to raw HTML, as suggested in https://github.com/readthedocs/recommonmark/issues/103

Comment 1

[Andrei Oprea [:andreio]]

dmose, ./mach doc doesn't seem to support html (converting the table from md table format to html table) or eval_rst.
Should we swap .md for .rst instead? Tested it out and any "online md to rst" tool does a decent job. Tables still won't work they need to be done manually.

Comment 2

[Dan Mosedale (:dmose, :dmosedale)]

searchfox suggests that eval_rst does seem to work in at least one other place in the tree. I verified, and https://firefox-source-docs.mozilla.org/toolkit/components/glean/index.html looks good, and if you click the "view source" link", it shows that some of the stuff you see is built from eval_rst.

Comment 3

[Dan Mosedale (:dmose, :dmosedale)]

eval_rst examples in web-platform-tests seem to be working, such as https://firefox-source-docs.mozilla.org/web-platform/index.html

Comment 4

[Andrei Oprea [:andreio]]

Attachment: Bug 1619381 - Fix tables in Markdown documentation browser/components/newtab

Comment 5

[Andrei Oprea [:andreio]]

Attachment: Bug 1619381 - Fix tables in Markdown documentation browser/components/newtab

Comment 6

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/a291f439f35a
Fix tables in Markdown documentation browser/components/newtab r=nanj

Comment 7

[Bogdan Tara[:bogdan_tara | bogdant]]

https://hg.mozilla.org/mozilla-central/rev/a291f439f35a

Comment 8

[Release mgmt bot [:sylvestre / :calixte / :marco for bugbug]]

Since the status are different for nightly and release, what's the status for beta?
For more information, please visit auto_nag documentation.