70 lines · plain
1LLVM Documentation2==================3 4LLVM's documentation is written in reStructuredText, a lightweight5plaintext markup language (file extension `.rst`). While the6reStructuredText documentation should be quite readable in source form, it7is mostly meant to be processed by the Sphinx documentation generation8system to create HTML pages which are hosted on <https://llvm.org/docs/> and9updated after every commit. Manpage output is also supported, see below.10 11If you instead would like to generate and view the HTML locally, install12Sphinx <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-html17 $BROWSER <build-dir>/docs/html/index.html18 19The mapping between reStructuredText files and generated documentation is20`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `https://llvm.org/docs/Foo.html`.21 22If you are interested in writing new documentation, you will want to read23`SphinxQuickstartTemplate.rst` which will get you writing documentation24very fast and includes examples of the most important reStructuredText25markup syntax.26 27Manpage Output28===============29 30Building the manpages is similar to building the HTML documentation. The31primary difference is to use the `man` makefile target, instead of the32default (which is `html`). Sphinx then produces the man pages in the33directory `<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-man38 man -l <build-dir>/docs/man/FileCheck.139 40The correspondence between .rst files and man pages is41`docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.42These .rst files are also included during HTML generation so they are also43viewable online (as noted above) at e.g.44`https://llvm.org/docs/CommandGuide/Foo.html`.45 46Checking links47==============48 49The reachability of external links in the documentation can be checked by50running:51 52 cd llvm/docs/53 sphinx-build -b linkcheck . _build/lintcheck/54 # report will be generated in _build/lintcheck/output.txt55 56Doxygen page Output57==============58 59Install doxygen <https://www.doxygen.nl/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.60 61 cd <build-dir>62 cmake -DLLVM_ENABLE_DOXYGEN=On <llvm-top-src-dir>63 make doxygen-llvm # for LLVM docs64 make doxygen-clang # for clang docs65 66It will generate html in67 68 <build-dir>/docs/doxygen/html # for LLVM docs69 <build-dir>/tools/clang/docs/doxygen/html # for clang docs70