This Page

Quick search

This document is meant to get you writing documentation as fast as possible
even if you have no previous experience with Sphinx. The goal is to take
someone in the state of “I want to write documentation and get it added to
LLVM’s docs” and turn that into useful documentation mailed to llvm-commits
with as little nonsense as possible.

You can find this document in docs/SphinxQuickstartTemplate.rst. You
should copy it, open the new file in your text editor, write your docs, and
then send the new document to llvm-commits for review.

Focus on content. It is easy to fix the Sphinx (reStructuredText) syntax
later if necessary, although reStructuredText tries to imitate common
plain-text conventions so it should be quite natural. A basic knowledge of
reStructuredText syntax is useful when writing the document, so the last
~half of this document (starting with Example Section) gives examples
which should cover 99% of use cases.

Let me say that again: focus on content.

Once you have finished with the content, please send the .rst file to
llvm-commits for review.

Common names for the first section are Introduction, Overview, or
Background.

If possible, make your document a “how to”. Give it a name HowTo*.rst
like the other “how to” documents. This format is usually the easiest
for another person to understand and also the most useful.

You generally should not be writing documentation other than a “how to”
unless there is already a “how to” about your topic. The reason for this
is that without a “how to” document to read first, it is difficult for a
person to understand a more advanced document.

Focus on content (yes, I had to say it again).

The rest of this document shows example reStructuredText markup constructs
that are meant to be read by you in your text editor after you have copied
this file into a new file for the documentation you are about to write.

Headings (like ExampleSection just above) give your document
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.

Make a link like this. There is also a more
sophisticated syntax which can be more readable for longer links since
it disrupts the flow less. You can put the .._`linktext`:<URL> block
pretty much anywhere later in the document.