From 61c7ee42e2db478bc7027acb98b78162e71be3a7 Mon Sep 17 00:00:00 2001 From: "Michael J. Spencer" Date: Mon, 23 Jul 2018 19:49:34 +0000 Subject: [PATCH] [docs] Add support for Markdown documentation in Sphinx Differential Revision: https://reviews.llvm.org/D44910 llvm-svn: 337730 --- llvm/docs/MarkdownQuickstartTemplate.md | 157 ++++++++++++++++++++++++++++++++ llvm/docs/conf.py | 4 +- llvm/docs/index.rst | 5 + 3 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 llvm/docs/MarkdownQuickstartTemplate.md diff --git a/llvm/docs/MarkdownQuickstartTemplate.md b/llvm/docs/MarkdownQuickstartTemplate.md new file mode 100644 index 0000000..7341521 --- /dev/null +++ b/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]: ` 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 diff --git a/llvm/docs/conf.py b/llvm/docs/conf.py index ce7df14..0fccb50 100644 --- a/llvm/docs/conf.py +++ b/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' diff --git a/llvm/docs/index.rst b/llvm/docs/index.rst index 2173f94..6a66454 100644 --- a/llvm/docs/index.rst +++ b/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 ================================= -- 2.7.4