69 lines
2.4 KiB
Plaintext
69 lines
2.4 KiB
Plaintext
|
LLVM Documentation
|
||
|
|
==================
|
||
|
|
|
||
|
|
LLVM's documentation is written in reStructuredText, a lightweight
|
||
|
|
plaintext markup language (file extension `.rst`). While the
|
||
|
|
reStructuredText documentation should be quite readable in source form, it
|
||
|
|
is mostly meant to be processed by the Sphinx documentation generation
|
||
|
|
system to create HTML pages which are hosted on <https://llvm.org/docs/> and
|
||
|
|
updated after every commit. Manpage output is also supported, see below.
|
||
|
|
|
||
|
|
If you instead would like to generate and view the HTML locally, install
|
||
|
|
Sphinx <http://sphinx-doc.org/> and then do:
|
||
|
|
|
||
|
|
cd <build-dir>
|
||
|
|
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
|
||
|
|
make -j3 docs-llvm-html
|
||
|
|
$BROWSER <build-dir>/docs//html/index.html
|
||
|
|
|
||
|
|
The mapping between reStructuredText files and generated documentation is
|
||
|
|
`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `https://llvm.org/docs/Foo.html`.
|
||
|
|
|
||
|
|
If you are interested in writing new documentation, you will want to read
|
||
|
|
`SphinxQuickstartTemplate.rst` which will get you writing documentation
|
||
|
|
very fast and includes examples of the most important reStructuredText
|
||
|
|
markup syntax.
|
||
|
|
|
||
|
|
Manpage Output
|
||
|
|
===============
|
||
|
|
|
||
|
|
Building the manpages is similar to building the HTML documentation. The
|
||
|
|
primary difference is to use the `man` makefile target, instead of the
|
||
|
|
default (which is `html`). Sphinx then produces the man pages in the
|
||
|
|
directory `<build-dir>/docs/man/`.
|
||
|
|
|
||
|
|
cd <build-dir>
|
||
|
|
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
|
||
|
|
make -j3 docs-llvm-man
|
||
|
|
man -l >build-dir>/docs/man/FileCheck.1
|
||
|
|
|
||
|
|
The correspondence between .rst files and man pages is
|
||
|
|
`docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.
|
||
|
|
These .rst files are also included during HTML generation so they are also
|
||
|
|
viewable online (as noted above) at e.g.
|
||
|
|
`https://llvm.org/docs/CommandGuide/Foo.html`.
|
||
|
|
|
||
|
|
Checking links
|
||
|
|
==============
|
||
|
|
|
||
|
|
The reachability of external links in the documentation can be checked by
|
||
|
|
running:
|
||
|
|
|
||
|
|
cd docs/
|
||
|
|
make -f Makefile.sphinx linkcheck
|
||
|
|
|
||
|
|
Doxygen page Output
|
||
|
|
==============
|
||
|
|
|
||
|
|
Install doxygen <http://www.stack.nl/~dimitri/doxygen/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.
|
||
|
|
|
||
|
|
cd <build-dir>
|
||
|
|
cmake -DLLVM_ENABLE_DOXYGEN=On <llvm-top-src-dir>
|
||
|
|
make doxygen-llvm # for LLVM docs
|
||
|
|
make doxygen-clang # for clang docs
|
||
|
|
|
||
|
|
It will generate html in
|
||
|
|
|
||
|
|
<build-dir>/docs/doxygen/html # for LLVM docs
|
||
|
|
<build-dir>/tools/clang/docs/doxygen/html # for clang docs
|