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