|
150
|
1 # Markdown Quickstart Template
|
|
|
2
|
|
|
3 ## Introduction and Quickstart
|
|
|
4
|
|
|
5 This document is meant to get you writing documentation as fast as possible
|
|
|
6 even if you have no previous experience with Markdown. The goal is to take
|
|
|
7 someone in the state of "I want to write documentation and get it added to
|
|
|
8 LLVM's docs" and turn that into useful documentation mailed to llvm-commits
|
|
|
9 with as little nonsense as possible.
|
|
|
10
|
|
|
11 You can find this document in `docs/MarkdownQuickstartTemplate.md`. You
|
|
|
12 should copy it, open the new file in your text editor, write your docs, and
|
|
|
13 then send the new document to llvm-commits for review.
|
|
|
14
|
|
|
15 Focus on *content*. It is easy to fix the Markdown syntax
|
|
|
16 later if necessary, although Markdown tries to imitate common
|
|
|
17 plain-text conventions so it should be quite natural. A basic knowledge of
|
|
|
18 Markdown syntax is useful when writing the document, so the last
|
|
|
19 ~half of this document (starting with [Example Section](#example-section)) gives examples
|
|
|
20 which should cover 99% of use cases.
|
|
|
21
|
|
|
22 Let me say that again: focus on *content*. But if you really need to verify
|
|
|
23 Sphinx's output, see `docs/README.txt` for information.
|
|
|
24
|
|
|
25 Once you have finished with the content, please send the `.md` file to
|
|
|
26 llvm-commits for review.
|
|
|
27
|
|
|
28 ## Guidelines
|
|
|
29
|
|
|
30 Try to answer the following questions in your first section:
|
|
|
31
|
|
|
32 1. Why would I want to read this document?
|
|
|
33
|
|
|
34 2. What should I know to be able to follow along with this document?
|
|
|
35
|
|
|
36 3. What will I have learned by the end of this document?
|
|
|
37
|
|
|
38 Common names for the first section are `Introduction`, `Overview`, or
|
|
|
39 `Background`.
|
|
|
40
|
|
|
41 If possible, make your document a "how to". Give it a name `HowTo*.md`
|
|
|
42 like the other "how to" documents. This format is usually the easiest
|
|
|
43 for another person to understand and also the most useful.
|
|
|
44
|
|
|
45 You generally should not be writing documentation other than a "how to"
|
|
|
46 unless there is already a "how to" about your topic. The reason for this
|
|
|
47 is that without a "how to" document to read first, it is difficult for a
|
|
|
48 person to understand a more advanced document.
|
|
|
49
|
|
|
50 Focus on content (yes, I had to say it again).
|
|
|
51
|
|
|
52 The rest of this document shows example Markdown markup constructs
|
|
|
53 that are meant to be read by you in your text editor after you have copied
|
|
|
54 this file into a new file for the documentation you are about to write.
|
|
|
55
|
|
|
56 ## Example Section
|
|
|
57
|
|
|
58 Your text can be *emphasized*, **bold**, or `monospace`.
|
|
|
59
|
|
|
60 Use blank lines to separate paragraphs.
|
|
|
61
|
|
|
62 Headings (like `Example Section` just above) give your document its
|
|
|
63 structure.
|
|
|
64
|
|
|
65 ### Example Subsection
|
|
|
66
|
|
173
|
67 Make a link [like this](https://llvm.org/). There is also a more
|
|
150
|
68 sophisticated syntax which [can be more readable] for longer links since
|
|
|
69 it disrupts the flow less. You can put the `[link name]: <URL>` block
|
|
|
70 pretty much anywhere later in the document.
|
|
|
71
|
|
|
72 [can be more readable]: http://en.wikipedia.org/wiki/LLVM
|
|
|
73
|
|
|
74 Lists can be made like this:
|
|
|
75
|
|
|
76 1. A list starting with `[0-9].` will be automatically numbered.
|
|
|
77
|
|
|
78 1. This is a second list element.
|
|
|
79
|
|
|
80 1. Use indentation to create nested lists.
|
|
|
81
|
|
|
82 You can also use unordered lists.
|
|
|
83
|
|
|
84 * Stuff.
|
|
|
85
|
|
|
86 + Deeper stuff.
|
|
|
87
|
|
|
88 * More stuff.
|
|
|
89
|
|
|
90 #### Example Subsubsection
|
|
|
91
|
|
|
92 You can make blocks of code like this:
|
|
|
93
|
|
|
94 ```
|
|
|
95 int main() {
|
|
|
96 return 0;
|
|
|
97 }
|
|
|
98 ```
|
|
|
99
|
|
|
100 As an extension to markdown, you can also specify a highlighter to use.
|
|
|
101
|
|
|
102 ``` C++
|
|
|
103 int main() {
|
|
|
104 return 0;
|
|
|
105 }
|
|
|
106 ```
|
|
|
107
|
|
|
108 For a shell session, use a `console` code block.
|
|
|
109
|
|
|
110 ```console
|
|
|
111 $ echo "Goodbye cruel world!"
|
|
|
112 $ rm -rf /
|
|
|
113 ```
|
|
|
114
|
|
|
115 If you need to show LLVM IR use the `llvm` code block.
|
|
|
116
|
|
|
117 ``` llvm
|
|
|
118 define i32 @test1() {
|
|
|
119 entry:
|
|
|
120 ret i32 0
|
|
|
121 }
|
|
|
122 ```
|
|
|
123
|
|
|
124 Some other common code blocks you might need are `c`, `objc`, `make`,
|
|
|
125 and `cmake`. If you need something beyond that, you can look at the [full
|
|
|
126 list] of supported code blocks.
|
|
|
127
|
|
|
128 [full list]: http://pygments.org/docs/lexers/
|
|
|
129
|
|
|
130 However, don't waste time fiddling with syntax highlighting when you could
|
|
|
131 be adding meaningful content. When in doubt, show preformatted text
|
|
|
132 without any syntax highlighting like this:
|
|
|
133
|
|
|
134 .
|
|
|
135 +:.
|
|
|
136 ..:: ::
|
|
|
137 .++:+:: ::+:.:.
|
|
|
138 .:+ :
|
|
|
139 ::.::..:: .+.
|
|
|
140 ..:+ :: :
|
|
|
141 ......+:. ..
|
|
|
142 :++. .. :
|
|
|
143 .+:::+:: :
|
|
|
144 .. . .+ ::
|
|
|
145 +.: .::+.
|
|
|
146 ...+. .: .
|
|
|
147 .++:..
|
|
|
148 ...
|
|
|
149
|
|
|
150 ##### Hopefully you won't need to be this deep
|
|
|
151
|
|
|
152 If you need to do fancier things than what has been shown in this document,
|
|
|
153 you can mail the list or check the [Common Mark spec]. Sphinx specific
|
|
|
154 integration documentation can be found in the [recommonmark docs].
|
|
|
155
|
|
|
156 [Common Mark spec]: http://spec.commonmark.org/0.28/
|
|
|
157 [recommonmark docs]: http://recommonmark.readthedocs.io/en/latest/index.html
|
