[docs] Add Markdown support to Sphinx

[chandlerc]

Summary

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 conf.py files.

[lebedev.ri]

Missing context (-U99999)

[chandlerc]

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.

docs/MarkdownQuickstartTemplate.md

102

capital or lowercase c here?

[llvm-commits]

• msg-24322-420.txt162 BDownload

[chandlerc]

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

[chandlerc]

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

[chandlerc]

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

[paquette]

llvm/docs/MarkdownQuickstartTemplate.md

6 ↗

(On Diff #156070)

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

[paquette]

llvm/docs/MarkdownQuickstartTemplate.md

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.

[Bigcheese]

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

[sqlbyme]

Hi,
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.

-me

[chandlerc]

llvm/docs/MarkdownQuickstartTemplate.md

6 ↗

(On Diff #156070)

Did you miss this comment Michael?

[Bigcheese]

llvm/docs/MarkdownQuickstartTemplate.md

6 ↗

(On Diff #156070)

It got applied, sorry for not making that clear.

[sylvestre.ledru]

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!

[chandlerc]

In D44910#1211470, @sylvestre.ledru wrote:

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?

docs/MarkdownQuickstartTemplate.md

+# Markdown Quickstart Template
+
+## Introduction and Quickstart
+
+This document is meant to get you writing documentation as fast as possible
+even if you have no previous experience with Sphinx. The goal is to take
+someone in the state of "I want to write documentation and get it added to
+LLVM's docs" and turn that into useful documentation mailed to llvm-commits
+with as little nonsense as possible.
+
+You can find this document in `docs/MarkdownQuickstartTemplate.md`. You
+should copy it, open the new file in your text editor, write your docs, and
+then send the new document to llvm-commits for review.
+
+Focus on *content*. It is easy to fix the Markdown syntax
+later if necessary, although Markdown tries to imitate common
+plain-text conventions so it should be quite natural. A basic knowledge of
+Markdown syntax is useful when writing the document, so the last
+~half of this document (starting with [Example Section](#example-section)) gives examples
+which should cover 99% of use cases.
+
+Let me say that again: focus on *content*. But if you really need to verify
+Sphinx's output, see `docs/README.txt` for information.
+
+Once you have finished with the content, please send the `.md` file to
+llvm-commits for review.
+
+## Guidelines
+
+Try to answer the following questions in your first section:
+
+1. Why would I want to read this document?
+
+2. What should I know to be able to follow along with this document?
+
+3. What will I have learned by the end of this document?
+
+Common names for the first section are `Introduction`, `Overview`, or
+`Background`.
+
+If possible, make your document a "how to". Give it a name `HowTo*.md`
+like the other "how to" documents. This format is usually the easiest
+for another person to understand and also the most useful.
+
+You generally should not be writing documentation other than a "how to"
+unless there is already a "how to" about your topic. The reason for this
+is that without a "how to" document to read first, it is difficult for a
+person to understand a more advanced document.
+
+Focus on content (yes, I had to say it again).
+
+The rest of this document shows example Markdown markup constructs
+that are meant to be read by you in your text editor after you have copied
+this file into a new file for the documentation you are about to write.
+
+## Example Section
+
+Your text can be *emphasized*, **bold**, or `monospace`.
+
+Use blank lines to separate paragraphs.
+
+Headings (like `Example Section` just above) give your document its
+structure.
+
+### Example Subsection
+
+Make a link [like this](http://llvm.org/). There is also a more
+sophisticated syntax which [can be more readable] for longer links since
+it disrupts the flow less. You can put the `[link name]: <URL>` block
+pretty much anywhere later in the document.
+
+[can be more readable]: http://en.wikipedia.org/wiki/LLVM
+
+Lists can be made like this:
+
+1. A list starting with `[0-9].` will be automatically numbered.
+
+1. This is a second list element.
+
+   1. Use indentation to create nested lists.
+
+You can also use unordered lists.
+
+* Stuff.
+
+  + Deeper stuff.
+
+* More stuff.
+
+#### Example Subsubsection
+
+You can make blocks of code like this:
+
+```
+int main() {
+  return 0;
+}
+```
+
+As an extension to markdown, you can also specify a highlighter to use.
+
+``` C++
+int main() {
+  return 0;
+}
+```
+
+For a shell session, use a `console` code block.
+
+```console
+$ echo "Goodbye cruel world!"
+$ rm -rf /
+```
+
+If you need to show LLVM IR use the `llvm` code block.
+
+``` llvm
+define i32 @test1() {
+entry:
+  ret i32 0
+}
+```
+
+Some other common code blocks you might need are `c`, `objc`, `make`,
+and `cmake`. If you need something beyond that, you can look at the [full
+list] of supported code blocks.
+
+[full list]: http://pygments.org/docs/lexers/
+
+However, don't waste time fiddling with syntax highlighting when you could
+be adding meaningful content. When in doubt, show preformatted text
+without any syntax highlighting like this:
+
+                          .
+                           +:.
+                       ..:: ::
+                    .++:+:: ::+:.:.
+                   .:+           :
+            ::.::..::            .+.
+          ..:+    ::              :
+    ......+:.                    ..
+          :++.    ..              :
+            .+:::+::              :
+            ..   . .+            ::
+                     +.:      .::+.
+                      ...+. .: .
+                         .++:..
+                          ...
+
+##### Hopefully you won't need to be this deep
+
+If you need to do fancier things than what has been shown in this document,
+you can mail the list or check the [Common Mark spec].  Sphinx specific
+integration documentation can be found in the [recommonmark docs].
+
+[Common Mark spec]: http://spec.commonmark.org/0.28/
+[recommonmark docs]: http://recommonmark.readthedocs.io/en/latest/index.html

docs/conf.py

 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+
+source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'

docs/index.rst

    yaml2obj
    HowToSubmitABug
    SphinxQuickstartTemplate
+   MarkdownQuickstartTemplate
    Phabricator
    TestingGuide
    tutorial/index