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