openmp/docs/README.txt

   1 OpenMP LLVM Documentation
   2 ==================
   3
   4 OpenMP 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 -DCMAKE_MODULE_PATH=/path/to/llvm/cmake/modules <src-dir>
  16     make docs-openmp-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>/projects/openmp/docs//html/Foo.html` <->
  21 `https://openmp.llvm.org/docs/Foo.html`.
  22
  23 If you are interested in writing new documentation, you will want to read
  24 `llvm/docs/SphinxQuickstartTemplate.rst` which will get you writing
  25 documentation very fast and includes examples of the most important
  26 reStructuredText markup syntax.
  27
  28 Manpage Output
  29 ===============
  30
  31 Building the manpages is similar to building the HTML documentation. The
  32 primary difference is to use the `man` makefile target, instead of the
  33 default (which is `html`). Sphinx then produces the man pages in the
  34 directory `<build-dir>/docs/man/`.
  35
  36     cd <build-dir>
  37     cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
  38     make
  39     man -l >build-dir>/docs/man/FileCheck.1
  40
  41 The correspondence between .rst files and man pages is
  42 `docs/CommandGuide/Foo.rst` <-> `<build-dir>/projects/openmp/docs//man/Foo.1`.
  43 These .rst files are also included during HTML generation so they are also
  44 viewable online (as noted above) at e.g.
  45 `https://openmp.llvm.org/docs/CommandGuide/Foo.html`.