README.txt
1 LLVM Documentation 2 ================== 3 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. 10 11 If you instead would like to generate and view the HTML locally, install 12 Sphinx <http://sphinx-doc.org/> and then do: 13 14 cd docs/ 15 make -f Makefile.sphinx 16 $BROWSER _build/html/index.html 17 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`. 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 52
