llvm/docs/MarkdownQuickstartTemplate.md

   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
  67 Make a link [like this](https://llvm.org/). There is also a more
  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 [myst-parser docs].
 155
 156 [Common Mark spec]: http://spec.commonmark.org/0.28/
 157 [myst-parser docs]: https://myst-parser.readthedocs.io/en/latest/
 158
 159 ## Generating the documentation
 160
 161 see [Sphinx Quickstart Template](project:SphinxQuickstartTemplate.rst#Generating the documentation)