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 reachibility of external links in the documentation can be checked by 48running: 49 50 cd docs/ 51 make -f Makefile.sphinx linkcheck 52