llvm/docs/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 <https://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` <-> `https://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 `https://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 llvm/docs/
  53     sphinx-build -b linkcheck . _build/lintcheck/
  54     # report will be generated in _build/lintcheck/output.txt
  55
  56 Doxygen page Output
  57 ==============
  58
  59 Install 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 docs
  64     make doxygen-clang # for clang docs
  65
  66 It will generate html in
  67
  68     <build-dir>/docs/doxygen/html # for LLVM docs
  69     <build-dir>/tools/clang/docs/doxygen/html # for clang docs