Sphinx Quickstart Template¶
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.
Overview¶
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.
How to use this template¶
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.
To view the restructuredText source file for this article, click Show Source on the right sidebar.
Example Section¶
An article can contain one or more sections (i.e., headings). Sections (like Example Section
above) help give your document its
structure. Use the same kind of adornments (e.g. ======
vs. ------
)
as are used in this document. The adornment must be the same length as the
text above it. For Vim users, variations of yypVr=
might be handy.
Example Nested Subsection¶
Subsections can also be nested beneath other subsections. For more information on sections, see Sphinx’s reStructuredText Primer.
Text Formatting¶
Text can be emphasized, bold, or monospace
.
To create a new paragraph, simply insert a blank line.
Links¶
You can format a link like this. A more sophisticated syntax allows you to place the .. _`link text`: <URL>
block
pretty much anywhere else in the document. This is useful when linking to especially long URLs.
Lists¶
restructuredText allows you to create ordered lists…
A list starting with
#.
will be automatically numbered.This is a second list element.
Use indentation to create nested lists.
…as well as unordered lists:
Stuff.
Deeper stuff.
More stuff.
Code Blocks¶
You can make blocks of code like this:
int main() {
return 0;
}
For a shell session, use a console
code block (some existing docs use
bash
):
$ echo "Goodbye cruel world!"
$ rm -rf /
If you need to show LLVM IR use the llvm
code block.
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.
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:
.
+:.
..:: ::
.++:+:: ::+:.:.
.:+ :
::.::..:: .+.
..:+ :: :
......+:. ..
:++. .. :
.+:::+:: :
.. . .+ ::
+.: .::+.
...+. .: .
.++:..
...
Generating the documentation¶
You can generate the HTML documentation from the sources locally if you want to
see what they would look like. In addition to the normal
build tools
you need to install Sphinx and the necessary extensions
using the following command inside the llvm-project
checkout:
pip install --user -r ./llvm/docs/requirements.txt
Then run cmake to build the documentation inside the llvm-project
checkout:
mkdir build
cd build
cmake -DLLVM_ENABLE_SPHINX=On ../llvm
cmake --build . --target docs-llvm-html
In case you already have the Cmake build set up and want to reuse that,
just set the CMake variable LLVM_ENABLE_SPHINX=On
.
After that you find the generated documentation in build/docs/html
folder.