Page MenuHomePhabricator

[docs] Add Markdown support to Sphinx

Authored by chandlerc on Mar 26 2018, 2:58 PM.



This adds support for Markdown documentation in Sphinx and adds a document (copied from the Sphinx template) on how to use it.

Before this goes in, any systems we have that generate docs will need to add the recommonmark python package.

Any other projects (clang, lld) that want to add Markdown support will need to do a similar modification to their files.

Diff Detail


Event Timeline

Bigcheese created this revision.Mar 26 2018, 2:58 PM

Missing context (-U99999)

FWIW, I'm really, really happy to have this. =D

But we should hear from others whether they're happy with this direction. Also, should we update any of our documentation recommending one format or the other? I feel like markdown has "won" in the same sense that GitHub has "won" -- it's the place with the growing ecosystem, even when its functionality is actually inferior to ReStructuredText. My inclination is always to go with ecosystem, but others may have different opinions here.

102 ↗(On Diff #139855)

capital or lowercase c here?

chandlerc commandeered this revision.Jul 18 2018, 7:22 AM
chandlerc edited reviewers, added: Bigcheese; removed: chandlerc.

Ping? (Commandeering to post an updated version of this patch now that I have added a document that would use this...)

chandlerc updated this revision to Diff 156070.Jul 18 2018, 7:23 AM

Updated to reflect the new .md file in the tree.

(Feel free to commandeer back if someone else wants to land this)

paquette added inline comments.
6 ↗(On Diff #156070)

Should this be "Markdown", not "Sphinx"?

paquette added inline comments.Jul 18 2018, 9:55 AM
6 ↗(On Diff #156070)

Actually wait no, that comment was silly. My initial response was "wait, why are we talking about Sphinx in a document explaining how to use Markdown?"

It might be good to just not mention Sphinx at all in the document and just keep it to Markdown, modulo the "if you need to verify Sphinx's output" section.

This just needs the recommonmark python package added on whatever server builds the docs.

I have added the recommonmark python package to the server. It should be available to the doc bot now so I would say go ahead and land this patch and let's see what happens.


This revision was not accepted when it landed; it landed in state Needs Review.Jul 19 2018, 4:46 PM
Closed by commit rL337509: [docs] Add support for Markdown documentation in Sphinx (authored by mspencer, committed by ). · Explain Why
This revision was automatically updated to reflect the committed changes.
chandlerc added inline comments.Jul 19 2018, 4:55 PM
6 ↗(On Diff #156070)

Did you miss this comment Michael?

Bigcheese added inline comments.Jul 19 2018, 5:00 PM
6 ↗(On Diff #156070)

It got applied, sorry for not making that clear.

Unfortunately, recommonmark isn't available on some older ubuntu (no backport available) & debian (a backport is available).
This will make the life of some of us harder!

Unfortunately, recommonmark isn't available on some older ubuntu (no backport available) & debian (a backport is available).
This will make the life of some of us harder!

While unfortunate, I tihnk this is still worthwhile as markdown seems to be pretty clearly the winning direction here....

And given that you don't need to build the documentation at all, it seems relatively low impact? Maybe we can add detection for recommonmark and if it fails disable the sphinx stuff cleanly in cmake?