<div dir="ltr"><div>It seems the bots have a very old version of Sphinx. The
<span style="font-size:small;background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial;float:none;display:inline">source_suffix option</span> was extended to support lists in 1.3 (current version is 1.8). I've asked for an upgrade and will revert shortly (15m) if it takes longer to get that sorted out.</div><br clear="all"><div><div dir="ltr" class="m_3794539925955686434gmail_signature" data-smartmail="gmail_signature">- Michael Spencer</div></div><br></div><br><div class="gmail_quote"><div dir="ltr">On Thu, Jul 19, 2018 at 4:46 PM Michael J. Spencer via llvm-commits <<a href="mailto:llvm-commits@lists.llvm.org" target="_blank">llvm-commits@lists.llvm.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: mspencer<br>
Date: Thu Jul 19 16:40:58 2018<br>
New Revision: 337509<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=337509&view=rev" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project?rev=337509&view=rev</a><br>
Log:<br>
[docs] Add support for Markdown documentation in Sphinx<br>
<br>
Differential Revision: <a href="https://reviews.llvm.org/D44910" rel="noreferrer" target="_blank">https://reviews.llvm.org/D44910</a><br>
<br>
Added:<br>
llvm/trunk/docs/MarkdownQuickstartTemplate.md<br>
Modified:<br>
llvm/trunk/docs/conf.py<br>
llvm/trunk/docs/index.rst<br>
<br>
Added: llvm/trunk/docs/MarkdownQuickstartTemplate.md<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/MarkdownQuickstartTemplate.md?rev=337509&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/MarkdownQuickstartTemplate.md?rev=337509&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/MarkdownQuickstartTemplate.md (added)<br>
+++ llvm/trunk/docs/MarkdownQuickstartTemplate.md Thu Jul 19 16:40:58 2018<br>
@@ -0,0 +1,157 @@<br>
+# Markdown Quickstart Template<br>
+<br>
+## Introduction and Quickstart<br>
+<br>
+This document is meant to get you writing documentation as fast as possible<br>
+even if you have no previous experience with Markdown. The goal is to take<br>
+someone in the state of "I want to write documentation and get it added to<br>
+LLVM's docs" and turn that into useful documentation mailed to llvm-commits<br>
+with as little nonsense as possible.<br>
+<br>
+You can find this document in `docs/MarkdownQuickstartTemplate.md`. You<br>
+should copy it, open the new file in your text editor, write your docs, and<br>
+then send the new document to llvm-commits for review.<br>
+<br>
+Focus on *content*. It is easy to fix the Markdown syntax<br>
+later if necessary, although Markdown tries to imitate common<br>
+plain-text conventions so it should be quite natural. A basic knowledge of<br>
+Markdown syntax is useful when writing the document, so the last<br>
+~half of this document (starting with [Example Section](#example-section)) gives examples<br>
+which should cover 99% of use cases.<br>
+<br>
+Let me say that again: focus on *content*. But if you really need to verify<br>
+Sphinx's output, see `docs/README.txt` for information.<br>
+<br>
+Once you have finished with the content, please send the `.md` file to<br>
+llvm-commits for review.<br>
+<br>
+## Guidelines<br>
+<br>
+Try to answer the following questions in your first section:<br>
+<br>
+1. Why would I want to read this document?<br>
+<br>
+2. What should I know to be able to follow along with this document?<br>
+<br>
+3. What will I have learned by the end of this document?<br>
+<br>
+Common names for the first section are `Introduction`, `Overview`, or<br>
+`Background`.<br>
+<br>
+If possible, make your document a "how to". Give it a name `HowTo*.md`<br>
+like the other "how to" documents. This format is usually the easiest<br>
+for another person to understand and also the most useful.<br>
+<br>
+You generally should not be writing documentation other than a "how to"<br>
+unless there is already a "how to" about your topic. The reason for this<br>
+is that without a "how to" document to read first, it is difficult for a<br>
+person to understand a more advanced document.<br>
+<br>
+Focus on content (yes, I had to say it again).<br>
+<br>
+The rest of this document shows example Markdown markup constructs<br>
+that are meant to be read by you in your text editor after you have copied<br>
+this file into a new file for the documentation you are about to write.<br>
+<br>
+## Example Section<br>
+<br>
+Your text can be *emphasized*, **bold**, or `monospace`.<br>
+<br>
+Use blank lines to separate paragraphs.<br>
+<br>
+Headings (like `Example Section` just above) give your document its<br>
+structure.<br>
+<br>
+### Example Subsection<br>
+<br>
+Make a link [like this](<a href="http://llvm.org/" rel="noreferrer" target="_blank">http://llvm.org/</a>). There is also a more<br>
+sophisticated syntax which [can be more readable] for longer links since<br>
+it disrupts the flow less. You can put the `[link name]: <URL>` block<br>
+pretty much anywhere later in the document.<br>
+<br>
+[can be more readable]: <a href="http://en.wikipedia.org/wiki/LLVM" rel="noreferrer" target="_blank">http://en.wikipedia.org/wiki/LLVM</a><br>
+<br>
+Lists can be made like this:<br>
+<br>
+1. A list starting with `[0-9].` will be automatically numbered.<br>
+<br>
+1. This is a second list element.<br>
+<br>
+ 1. Use indentation to create nested lists.<br>
+<br>
+You can also use unordered lists.<br>
+<br>
+* Stuff.<br>
+<br>
+ + Deeper stuff.<br>
+<br>
+* More stuff.<br>
+<br>
+#### Example Subsubsection<br>
+<br>
+You can make blocks of code like this:<br>
+<br>
+```<br>
+int main() {<br>
+ return 0;<br>
+}<br>
+```<br>
+<br>
+As an extension to markdown, you can also specify a highlighter to use.<br>
+<br>
+``` C++<br>
+int main() {<br>
+ return 0;<br>
+}<br>
+```<br>
+<br>
+For a shell session, use a `console` code block.<br>
+<br>
+```console<br>
+$ echo "Goodbye cruel world!"<br>
+$ rm -rf /<br>
+```<br>
+<br>
+If you need to show LLVM IR use the `llvm` code block.<br>
+<br>
+``` llvm<br>
+define i32 @test1() {<br>
+entry:<br>
+ ret i32 0<br>
+}<br>
+```<br>
+<br>
+Some other common code blocks you might need are `c`, `objc`, `make`,<br>
+and `cmake`. If you need something beyond that, you can look at the [full<br>
+list] of supported code blocks.<br>
+<br>
+[full list]: <a href="http://pygments.org/docs/lexers/" rel="noreferrer" target="_blank">http://pygments.org/docs/lexers/</a><br>
+<br>
+However, don't waste time fiddling with syntax highlighting when you could<br>
+be adding meaningful content. When in doubt, show preformatted text<br>
+without any syntax highlighting like this:<br>
+<br>
+ .<br>
+ +:.<br>
+ ..:: ::<br>
+ .++:+:: ::+:.:.<br>
+ .:+ :<br>
+ ::.::..:: .+.<br>
+ ..:+ :: :<br>
+ ......+:. ..<br>
+ :++. .. :<br>
+ .+:::+:: :<br>
+ .. . .+ ::<br>
+ +.: .::+.<br>
+ ...+. .: .<br>
+ .++:..<br>
+ ...<br>
+<br>
+##### Hopefully you won't need to be this deep<br>
+<br>
+If you need to do fancier things than what has been shown in this document,<br>
+you can mail the list or check the [Common Mark spec]. Sphinx specific<br>
+integration documentation can be found in the [recommonmark docs].<br>
+<br>
+[Common Mark spec]: <a href="http://spec.commonmark.org/0.28/" rel="noreferrer" target="_blank">http://spec.commonmark.org/0.28/</a><br>
+[recommonmark docs]: <a href="http://recommonmark.readthedocs.io/en/latest/index.html" rel="noreferrer" target="_blank">http://recommonmark.readthedocs.io/en/latest/index.html</a><br>
<br>
Modified: llvm/trunk/docs/conf.py<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/conf.py?rev=337509&r1=337508&r2=337509&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/conf.py?rev=337509&r1=337508&r2=337509&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/conf.py (original)<br>
+++ llvm/trunk/docs/conf.py Thu Jul 19 16:40:58 2018<br>
@@ -31,7 +31,9 @@ extensions = ['sphinx.ext.intersphinx',<br>
templates_path = ['_templates']<br>
<br>
# The suffix of source filenames.<br>
-source_suffix = '.rst'<br>
+source_suffix = ['.rst', '.md']<br>
+<br>
+source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}<br>
<br>
# The encoding of source files.<br>
#source_encoding = 'utf-8-sig'<br>
<br>
Modified: llvm/trunk/docs/index.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=337509&r1=337508&r2=337509&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=337509&r1=337508&r2=337509&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/index.rst (original)<br>
+++ llvm/trunk/docs/index.rst Thu Jul 19 16:40:58 2018<br>
@@ -79,6 +79,7 @@ representation.<br>
yaml2obj<br>
HowToSubmitABug<br>
SphinxQuickstartTemplate<br>
+ MarkdownQuickstartTemplate<br>
Phabricator<br>
TestingGuide<br>
tutorial/index<br>
@@ -292,6 +293,7 @@ For API clients and LLVM developers.<br>
XRayFDRFormat<br>
PDB/index<br>
CFIVerify<br>
+ SpeculativeLoadHardening<br>
<br>
:doc:`WritingAnLLVMPass`<br>
Information on how to write LLVM transformations and analyses.<br>
@@ -425,6 +427,9 @@ For API clients and LLVM developers.<br>
:doc:`CFIVerify`<br>
A description of the verification tool for Control Flow Integrity.<br>
<br>
+:doc:`SpeculativeLoadHardening`<br>
+ A description of the Speculative Load Hardening mitigation for Spectre v1.<br>
+<br>
Development Process Documentation<br>
=================================<br>
<br>
<br>
<br>
_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@lists.llvm.org" target="_blank">llvm-commits@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits</a><br>
</blockquote></div>