1LLVM Documentation
2==================
3
4LLVM's documentation is written in reStructuredText, a lightweight
5plaintext markup language (file extension `.rst`). While the
6reStructuredText documentation should be quite readable in source form, it
7is mostly meant to be processed by the Sphinx documentation generation
8system to create HTML pages which are hosted on <http://llvm.org/docs/> and
9updated after every commit. Manpage output is also supported, see below.
10
11If you instead would like to generate and view the HTML locally, install
12Sphinx <http://sphinx-doc.org/> and then do:
13
14    cd docs/
15    make -f Makefile.sphinx
16    $BROWSER _build/html/index.html
17
18The mapping between reStructuredText files and generated documentation is
19`docs/Foo.rst` <-> `_build/html/Foo.html` <-> `http://llvm.org/docs/Foo.html`.
20
21If you are interested in writing new documentation, you will want to read
22`SphinxQuickstartTemplate.rst` which will get you writing documentation
23very fast and includes examples of the most important reStructuredText
24markup syntax.
25
26Manpage Output
27===============
28
29Building the manpages is similar to building the HTML documentation. The
30primary difference is to use the `man` makefile target, instead of the
31default (which is `html`). Sphinx then produces the man pages in the
32directory `_build/man/`.
33
34    cd docs/
35    make -f Makefile.sphinx man
36    man -l _build/man/FileCheck.1
37
38The correspondence between .rst files and man pages is
39`docs/CommandGuide/Foo.rst` <-> `_build/man/Foo.1`.
40These .rst files are also included during HTML generation so they are also
41viewable online (as noted above) at e.g.
42`http://llvm.org/docs/CommandGuide/Foo.html`.
43
44Checking links
45==============
46
47The reachability of external links in the documentation can be checked by
48running:
49
50    cd docs/
51    make -f Makefile.sphinx linkcheck
52