[docs] Add support for Markdown documentation in Sphinx

Differential Revision: https://reviews.llvm.org/D44910

llvm-svn: 337509

llvm/docs/MarkdownQuickstartTemplate.md

@@ -0,0 +1,157 @@
+# 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 Markdown. 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

llvm/docs/conf.py

@@ -31,7 +31,9 @@ extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
 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'

llvm/docs/index.rst

@@ -79,6 +79,7 @@ representation.
    yaml2obj
    HowToSubmitABug
    SphinxQuickstartTemplate
+   MarkdownQuickstartTemplate
    Phabricator
    TestingGuide
    tutorial/index
@@ -292,6 +293,7 @@ For API clients and LLVM developers.
    XRayFDRFormat
    PDB/index
    CFIVerify
+   SpeculativeLoadHardening
 
 :doc:`WritingAnLLVMPass`
    Information on how to write LLVM transformations and analyses.
@@ -425,6 +427,9 @@ For API clients and LLVM developers.
 :doc:`CFIVerify`
   A description of the verification tool for Control Flow Integrity.
 
+:doc:`SpeculativeLoadHardening`
+  A description of the Speculative Load Hardening mitigation for Spectre v1.
+
 Development Process Documentation
 =================================