Mercurial > hg > CbC > CbC_llvm

annotate docs/README.txt @ 122:36195a0db682

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merging ( incomplete )
author Shinji KONO <kono@ie.u-ryukyu.ac.jp>
date Fri, 17 Nov 2017 20:32:31 +0900
parents 803732b1fca8
children c2174574ed3a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
1 LLVM Documentation
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
2 ==================
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
3
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
4 LLVM's documentation is written in reStructuredText, a lightweight
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
5 plaintext markup language (file extension `.rst`). While the
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
6 reStructuredText documentation should be quite readable in source form, it
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
7 is mostly meant to be processed by the Sphinx documentation generation
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
8 system to create HTML pages which are hosted on <http://llvm.org/docs/> and
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
9 updated after every commit. Manpage output is also supported, see below.
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
10
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
11 If you instead would like to generate and view the HTML locally, install
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
12 Sphinx <http://sphinx-doc.org/> and then do:
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
13
120
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
14 cd <build-dir>
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
15 cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
16 make -j3 docs-llvm-html
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
17 $BROWSER <build-dir>/docs//html/index.html
0
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
18
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
19 The mapping between reStructuredText files and generated documentation is
120
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
20 `docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `http://llvm.org/docs/Foo.html`.
0
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
21
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
22 If you are interested in writing new documentation, you will want to read
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
23 `SphinxQuickstartTemplate.rst` which will get you writing documentation
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
24 very fast and includes examples of the most important reStructuredText
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
25 markup syntax.
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
26
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
27 Manpage Output
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
28 ===============
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
29
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
30 Building the manpages is similar to building the HTML documentation. The
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
31 primary difference is to use the `man` makefile target, instead of the
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
32 default (which is `html`). Sphinx then produces the man pages in the
120
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
33 directory `<build-dir>/docs/man/`.
0
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
34
120
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
35 cd <build-dir>
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
36 cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
37 make -j3 docs-llvm-man
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
38 man -l >build-dir>/docs/man/FileCheck.1
0
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
39
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
40 The correspondence between .rst files and man pages is
120
1172e4bd9c6f update 4.0.0
mir3636
parents: 95
diff changeset
41 `docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.
0
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
42 These .rst files are also included during HTML generation so they are also
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
43 viewable online (as noted above) at e.g.
95c75e76d11b LLVM 3.4
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents:
diff changeset
44 `http://llvm.org/docs/CommandGuide/Foo.html`.
77
54457678186b LLVM 3.6
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents: 0
diff changeset
45
54457678186b LLVM 3.6
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents: 0
diff changeset
46 Checking links
54457678186b LLVM 3.6
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents: 0
diff changeset
47 ==============
54457678186b LLVM 3.6
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents: 0
diff changeset
48
95
afa8332a0e37 LLVM 3.8
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents: 77
diff changeset
49 The reachability of external links in the documentation can be checked by
77
54457678186b LLVM 3.6
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents: 0
diff changeset
50 running:
54457678186b LLVM 3.6
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents: 0
diff changeset
51
54457678186b LLVM 3.6
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents: 0
diff changeset
52 cd docs/
54457678186b LLVM 3.6
Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
parents: 0
diff changeset
53 make -f Makefile.sphinx linkcheck
121
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
54
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
55 Doxygen page Output
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
56 ==============
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
57
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
58 Install doxygen <http://www.stack.nl/~dimitri/doxygen/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
59
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
60 cd <build-dir>
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
61 cmake -DLLVM_ENABLE_DOXYGEN=On <llvm-top-src-dir>
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
62 make doxygen-llvm # for LLVM docs
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
63 make doxygen-clang # for clang docs
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
64
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
65 It will generate html in
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
66
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
67 <build-dir>/docs/doxygen/html # for LLVM docs
803732b1fca8 LLVM 5.0
kono
parents: 120
diff changeset
68 <build-dir>/tools/clang/docs/doxygen/html # for clang docs