llvm.org GIT mirror llvm / d78e434
[docs] Reinstate r337730 - Add support for Markdown documentation in Sphinx. We think the bot is updated now, so trying this again. I'm landing it (with permission) as Michael is at a con at the moment. Actual patch largely by Michael Spencer. Differential Revision: https://reviews.llvm.org/D44910 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@338977 91177308-0d34-0410-b5e6-96231b3b80d8 Chandler Carruth 1 year, 2 months ago
3 changed file(s) with 165 addition(s) and 1 deletion(s). Raw diff Collapse all Expand all
0 # Markdown Quickstart Template
1
2 ## Introduction and Quickstart
3
4 This document is meant to get you writing documentation as fast as possible
5 even if you have no previous experience with Markdown. The goal is to take
6 someone in the state of "I want to write documentation and get it added to
7 LLVM's docs" and turn that into useful documentation mailed to llvm-commits
8 with as little nonsense as possible.
9
10 You can find this document in `docs/MarkdownQuickstartTemplate.md`. You
11 should copy it, open the new file in your text editor, write your docs, and
12 then send the new document to llvm-commits for review.
13
14 Focus on *content*. It is easy to fix the Markdown syntax
15 later if necessary, although Markdown tries to imitate common
16 plain-text conventions so it should be quite natural. A basic knowledge of
17 Markdown syntax is useful when writing the document, so the last
18 ~half of this document (starting with [Example Section](#example-section)) gives examples
19 which should cover 99% of use cases.
20
21 Let me say that again: focus on *content*. But if you really need to verify
22 Sphinx's output, see `docs/README.txt` for information.
23
24 Once you have finished with the content, please send the `.md` file to
25 llvm-commits for review.
26
27 ## Guidelines
28
29 Try to answer the following questions in your first section:
30
31 1. Why would I want to read this document?
32
33 2. What should I know to be able to follow along with this document?
34
35 3. What will I have learned by the end of this document?
36
37 Common names for the first section are `Introduction`, `Overview`, or
38 `Background`.
39
40 If possible, make your document a "how to". Give it a name `HowTo*.md`
41 like the other "how to" documents. This format is usually the easiest
42 for another person to understand and also the most useful.
43
44 You generally should not be writing documentation other than a "how to"
45 unless there is already a "how to" about your topic. The reason for this
46 is that without a "how to" document to read first, it is difficult for a
47 person to understand a more advanced document.
48
49 Focus on content (yes, I had to say it again).
50
51 The rest of this document shows example Markdown markup constructs
52 that are meant to be read by you in your text editor after you have copied
53 this file into a new file for the documentation you are about to write.
54
55 ## Example Section
56
57 Your text can be *emphasized*, **bold**, or `monospace`.
58
59 Use blank lines to separate paragraphs.
60
61 Headings (like `Example Section` just above) give your document its
62 structure.
63
64 ### Example Subsection
65
66 Make a link [like this](http://llvm.org/). There is also a more
67 sophisticated syntax which [can be more readable] for longer links since
68 it disrupts the flow less. You can put the `[link name]: ` block
69 pretty much anywhere later in the document.
70
71 [can be more readable]: http://en.wikipedia.org/wiki/LLVM
72
73 Lists can be made like this:
74
75 1. A list starting with `[0-9].` will be automatically numbered.
76
77 1. This is a second list element.
78
79 1. Use indentation to create nested lists.
80
81 You can also use unordered lists.
82
83 * Stuff.
84
85 + Deeper stuff.
86
87 * More stuff.
88
89 #### Example Subsubsection
90
91 You can make blocks of code like this:
92
93 ```
94 int main() {
95 return 0;
96 }
97 ```
98
99 As an extension to markdown, you can also specify a highlighter to use.
100
101 ``` C++
102 int main() {
103 return 0;
104 }
105 ```
106
107 For a shell session, use a `console` code block.
108
109 ```console
110 $ echo "Goodbye cruel world!"
111 $ rm -rf /
112 ```
113
114 If you need to show LLVM IR use the `llvm` code block.
115
116 ``` llvm
117 define i32 @test1() {
118 entry:
119 ret i32 0
120 }
121 ```
122
123 Some other common code blocks you might need are `c`, `objc`, `make`,
124 and `cmake`. If you need something beyond that, you can look at the [full
125 list] of supported code blocks.
126
127 [full list]: http://pygments.org/docs/lexers/
128
129 However, don't waste time fiddling with syntax highlighting when you could
130 be adding meaningful content. When in doubt, show preformatted text
131 without any syntax highlighting like this:
132
133 .
134 +:.
135 ..:: ::
136 .++:+:: ::+:.:.
137 .:+ :
138 ::.::..:: .+.
139 ..:+ :: :
140 ......+:. ..
141 :++. .. :
142 .+:::+:: :
143 .. . .+ ::
144 +.: .::+.
145 ...+. .: .
146 .++:..
147 ...
148
149 ##### Hopefully you won't need to be this deep
150
151 If you need to do fancier things than what has been shown in this document,
152 you can mail the list or check the [Common Mark spec]. Sphinx specific
153 integration documentation can be found in the [recommonmark docs].
154
155 [Common Mark spec]: http://spec.commonmark.org/0.28/
156 [recommonmark docs]: http://recommonmark.readthedocs.io/en/latest/index.html
3030 templates_path = ['_templates']
3131
3232 # The suffix of source filenames.
33 source_suffix = '.rst'
33 source_suffix = ['.rst', '.md']
34
35 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
3436
3537 # The encoding of source files.
3638 #source_encoding = 'utf-8-sig'
7878 yaml2obj
7979 HowToSubmitABug
8080 SphinxQuickstartTemplate
81 MarkdownQuickstartTemplate
8182 Phabricator
8283 TestingGuide
8384 tutorial/index
291292 XRayFDRFormat
292293 PDB/index
293294 CFIVerify
295 SpeculativeLoadHardening
294296
295297 :doc:`WritingAnLLVMPass`
296298 Information on how to write LLVM transformations and analyses.
423425
424426 :doc:`CFIVerify`
425427 A description of the verification tool for Control Flow Integrity.
428
429 :doc:`SpeculativeLoadHardening`
430 A description of the Speculative Load Hardening mitigation for Spectre v1.
426431
427432 Development Process Documentation
428433 =================================