llvm/docs/SphinxQuickstartTemplate.rst

   1 ==========================
   2 Sphinx Quickstart Template
   3 ==========================
   4
   5 This article is intended to take someone in the state of “I want to write documentation and get it added to LLVM’s docs” and help them start writing documentation as fast as possible and with as little nonsense as possible.
   6
   7 .. contents::
   8    :local:
   9
  10 Overview
  11 ========
  12
  13 LLVM documentation is written in `reStructuredText`_, a markup syntax similar to markdown (but much more powerful). The LLVM documentation site itself uses `Sphinx`_, a documentation generator originally written for Python documentation.
  14
  15 .. _`reStructuredText`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
  16 .. _`Sphinx`: http://www.sphinx-doc.org
  17
  18 How to use this template
  19 ========================
  20
  21 This article is located in ``docs/SphinxQuickstartTemplate.rst``. To use it as a template, make a copy and open it in a text editor. You can then write your docs, and then send the new article to llvm-commits for review.
  22
  23 To view the restructuredText source file for this article, click **Show Source** on the right sidebar.
  24
  25 Authoring Guidelines
  26 ====================
  27
  28 Focus on *content*. It is easy to fix the Sphinx (reStructuredText) syntax
  29 later if necessary, although reStructuredText tries to imitate common
  30 plain-text conventions so it should be quite natural. A basic knowledge of
  31 reStructuredText syntax is useful when writing the document, so the last
  32 ~half of this document (starting with `Example Section`_) gives examples
  33 which should cover 99% of use cases.
  34
  35 Let me say that again: focus on *content*. But if you really need to verify
  36 Sphinx's output, see ``docs/README.txt`` for information. Once you have finished with the content, please send the ``.rst`` file to
  37 llvm-commits for review.
  38
  39 Creating New Articles
  40 ---------------------
  41
  42 Before creating a new article, consider the following questions:
  43
  44 #. Why would I want to read this document?
  45
  46 #. What should I know to be able to follow along with this document?
  47
  48 #. What will I have learned by the end of this document?
  49
  50 A standard best practice is to make your articles task-oriented. You generally should not be writing documentation that isn't based around "how to" do something
  51 unless there's already an existing "how to" article for the topic you're documenting. The reason for this is that without a "how to" article to read first, it might be difficult for
  52 someone unfamiliar with the topic to understand a more advanced, conceptual article.
  53
  54 When creating a task-oriented article, follow existing LLVM articles by giving it a filename that starts with ``HowTo*.rst``. This format is usually the easiest for another person to understand and also the most useful.
  55
  56 Focus on content (yes, I had to say it again).
  57
  58 The rest of this document shows example reStructuredText markup constructs
  59 that are meant to be read by you in your text editor after you have copied
  60 this file into a new file for the documentation you are about to write.
  61
  62 Example Section
  63 ===============
  64
  65 An article can contain one or more sections (i.e., headings). Sections (like ``Example Section`` above) help give your document its
  66 structure. Use the same kind of adornments (e.g. ``======`` vs. ``------``)
  67 as are used in this document. The adornment must be the same length as the
  68 text above it. For Vim users, variations of ``yypVr=`` might be handy.
  69
  70 Example Nested Subsection
  71 -------------------------
  72
  73 Subsections can also be nested beneath other subsections. For more information on sections, see Sphinx's `reStructuredText Primer`_.
  74
  75 .. _`reStructuredText Primer`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
  76
  77 Text Formatting
  78 ===============
  79
  80 Text can be *emphasized*, **bold**, or ``monospace``.
  81
  82 To create a new paragraph, simply insert a blank line.
  83
  84 Links
  85 =====
  86
  87 You can format a link `like this <https://llvm.org/>`_. A more `sophisticated syntax`_ allows you to place the ``.. _`link text`: <URL>`` block
  88 pretty much anywhere else in the document. This is useful when linking to especially long URLs.
  89
  90 .. _`sophisticated syntax`: http://en.wikipedia.org/wiki/LLVM
  91
  92 Lists
  93 =====
  94
  95 restructuredText allows you to create ordered lists...
  96
  97 #. A list starting with ``#.`` will be automatically numbered.
  98
  99 #. This is a second list element.
 100
 101    #. Use indentation to create nested lists.
 102
 103 ...as well as unordered lists:
 104
 105 * Stuff.
 106
 107   + Deeper stuff.
 108
 109 * More stuff.
 110
 111 Code Blocks
 112 ===========
 113
 114 You can make blocks of code like this:
 115
 116 .. code-block:: c++
 117
 118    int main() {
 119      return 0;
 120    }
 121
 122 For a shell session, use a ``console`` code block (some existing docs use
 123 ``bash``):
 124
 125 .. code-block:: console
 126
 127    $ echo "Goodbye cruel world!"
 128    $ rm -rf /
 129
 130 If you need to show LLVM IR use the ``llvm`` code block.
 131
 132 .. code-block:: llvm
 133
 134    define i32 @test1() {
 135    entry:
 136      ret i32 0
 137    }
 138
 139 Some other common code blocks you might need are ``c``, ``objc``, ``make``,
 140 and ``cmake``. If you need something beyond that, you can look at the `full
 141 list`_ of supported code blocks.
 142
 143 .. _`full list`: http://pygments.org/docs/lexers/
 144
 145 However, don't waste time fiddling with syntax highlighting when you could
 146 be adding meaningful content. When in doubt, show preformatted text
 147 without any syntax highlighting like this:
 148
 149 ::
 150
 151                           .
 152                            +:.
 153                        ..:: ::
 154                     .++:+:: ::+:.:.
 155                    .:+           :
 156             ::.::..::            .+.
 157           ..:+    ::              :
 158     ......+:.                    ..
 159           :++.    ..              :
 160             .+:::+::              :
 161             ..   . .+            ::
 162                      +.:      .::+.
 163                       ...+. .: .
 164                          .++:..
 165                           ...
 166
 167
 168 Generating the documentation
 169 ============================
 170
 171 You can generate the HTML documentation from the sources locally if you want to
 172 see what they would look like. In addition to the normal
 173 `build tools <docs/GettingStarted.html>`_
 174 you need to install `Sphinx`_ and the
 175 `recommonmark <https://recommonmark.readthedocs.io/en/latest/>`_ extension.
 176
 177 On Debian you can install these with:
 178
 179 .. code-block:: console
 180
 181    sudo apt install -y sphinx-doc python-recommonmark-doc
 182
 183 On Ubuntu use pip to get an up-to-date version of recommonmark:
 184
 185 .. code-block:: console
 186
 187    sudo pip install sphinx recommonmark
 188
 189 Then run cmake to build the documentation inside the ``llvm-project`` checkout:
 190
 191 .. code-block:: console
 192
 193    mkdir build
 194    cd build
 195    cmake -DLLVM_ENABLE_SPHINX=On ../llvm
 196    cmake --build . --target docs-llvm-html
 197
 198 In case you already have the Cmake build set up and want to reuse that,
 199 just set the CMake variable ``LLVM_ENABLE_SPHINX=On``.
 200
 201 After that you find the generated documentation in ``build/docs/html``
 202 folder.