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