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 <build-dir> 15 cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir> 16 make -j3 docs-llvm-html 17 $BROWSER <build-dir>/docs//html/index.html 18 19 The mapping between reStructuredText files and generated documentation is 20 `docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `http://llvm.org/docs/Foo.html`. 21 22 If you are interested in writing new documentation, you will want to read 23 `SphinxQuickstartTemplate.rst` which will get you writing documentation 24 very fast and includes examples of the most important reStructuredText 25 markup syntax. 26 27 Manpage Output 28 =============== 29 30 Building the manpages is similar to building the HTML documentation. The 31 primary difference is to use the `man` makefile target, instead of the 32 default (which is `html`). Sphinx then produces the man pages in the 33 directory `<build-dir>/docs/man/`. 34 35 cd <build-dir> 36 cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir> 37 make -j3 docs-llvm-man 38 man -l >build-dir>/docs/man/FileCheck.1 39 40 The correspondence between .rst files and man pages is 41 `docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`. 42 These .rst files are also included during HTML generation so they are also 43 viewable online (as noted above) at e.g. 44 `http://llvm.org/docs/CommandGuide/Foo.html`. 45 46 Checking links 47 ============== 48 49 The reachability of external links in the documentation can be checked by 50 running: 51 52 cd docs/ 53 make -f Makefile.sphinx linkcheck 54
