Skip to content

Commit 1abac32

Browse files
robhoesrobhoes
authored
Merge pull request xapi-project#3167 from kc284/master
CA-261855: Generate automatically an image map for the API classes.
2 parents 01a87ac + 47ecbbf commit 1abac32

File tree

6 files changed

+60
-54
lines changed

6 files changed

+60
-54
lines changed

‎Makefile‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,10 @@ build: setup.data
1212

1313
doc: setup.data build
1414
$(SETUP) -doc $(DOCFLAGS)
15-
./jsapi.native -destdir _build/ocaml/doc -templdir ocaml/doc/templates
15+
./jsapi.native -destdir _build/ocaml/doc/html -templdir ocaml/doc/templates
16+
cp ocaml/doc/*.js ocaml/doc/*.html ocaml/doc/*.css _build/ocaml/doc/html
1617
./datamodel_main.native -closed -markdown -templdir ocaml/doc/templates _build/ocaml/doc/markdown
17-
cp ocaml/doc/*.dot ocaml/doc/doc-convert.sh _build/ocaml/doc/markdown
18+
cp ocaml/doc/*.dot ocaml/doc/doc-convert.sh _build/ocaml/doc
1819
find ocaml/doc -name "*.md" -not -name "README.md" -exec cp {} _build/ocaml/doc/markdown/ \;
1920

2021
test: setup.data build
@@ -95,9 +96,7 @@ install: setup.data rbac_static.csv
9596
# Libraries
9697
ocaml setup.ml -install
9798
# docs
98-
mkdir -p $(DESTDIR)$(DOCDIR)/html
99-
cp -r -L _build/ocaml/doc/api $(DESTDIR)$(DOCDIR)/html
100-
cd ocaml/doc && cp *.js *.html *.css $(DESTDIR)$(DOCDIR)/html
101-
scripts/install.sh 644 _build/ocaml/doc/branding.js $(DESTDIR)$(DOCDIR)/html/branding.js
99+
mkdir -p $(DESTDIR)$(DOCDIR)
100+
cp -r _build/ocaml/doc/html $(DESTDIR)$(DOCDIR)
102101
cp -r _build/ocaml/doc/markdown $(DESTDIR)$(DOCDIR)
103-
102+
cp _build/ocaml/doc/*.dot ocaml/doc/doc-convert.sh $(DESTDIR)$(DOCDIR)

‎ocaml/doc/README.md‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
11
# A note on generating locally the API reference
22

3-
Run `make doc`. The output is in `_build/ocaml/doc/markdown`.
3+
Run `make doc` in the repo root. This will output the API reference in html and
4+
markdown formats in `_build/ocaml/doc`.
45

5-
To view the markdown properly you will need to install `graphviz` so as to
6-
convert the dot files to images. To generate the API reference in other formats
7-
(currently docbook and pdf) you will need to install `pandoc`. For pdf format
8-
you will also need `pdflatex`.
6+
Both html and markdown reference images which need to be generated as a separate
7+
step from the `.dot` files. This requires `graphviz` to be installed.
98

10-
To convert the images only, run `sh doc-convert.sh`.
9+
To generate the images, run `sh doc-convert.sh` in `_build/ocaml/doc`. Now you
10+
can view the API reference by opening `_build/ocaml/doc/html/index.html` in your
11+
browser.
1112

12-
To generate the docbook run `sh doc-convert.sh --docbook`.
13+
To generate the API reference in other formats (currently docbook and pdf) you
14+
will need to install `pandoc`.
1315

14-
To generate the pdf run `sh doc-convert.sh --pdf`.
16+
To generate the docbook run `sh doc-convert.sh --docbook` in `_build/ocaml/doc`.
17+
18+
To generate the pdf you also need to install `pdflatex` (available within
19+
`texlive` distibutions). Then run `sh doc-convert.sh --pdf` in `_build/ocaml/doc`.

‎ocaml/doc/classes.dot‎

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,38 @@
1-
digraph "Xen-API Class Diagram" {
1+
digraph "graph" {
22
fontname="Verdana";
33
start=7;
44
layout=neato;
55
overlap=scale;
6+
size="3,5";
7+
resolution=210;
68

79
node [shape=box style=filled fillcolor=chocolate];
8-
host PBD SR VDI VBD VM VIF network PIF user session VGPU PGPU GPU_group;
10+
host [URL="?c=host"]
11+
PBD [URL="?c=PBD"]
12+
SR [URL="?c=SR"]
13+
VDI [URL="?c=VDI"]
14+
VBD [URL="?c=VBD"]
15+
VM [URL="?c=VM"]
16+
VIF [URL="?c=VIF"]
17+
network [URL="?c=network"]
18+
PIF [URL="?c=PIF"]
19+
user [URL="?c=user"]
20+
session [URL="?c=session"]
21+
VGPU [URL="?c=VGPU"]
22+
PGPU [URL="?c=PGPU"]
23+
GPU_group [URL="?c=GPU_group"];
924

1025
node [shape=ellipse style=filled fillcolor=wheat];
11-
pool task event host_cpu host_metrics SM VM_metrics VM_guest_metrics
12-
console PIF_metrics;
26+
pool [URL="?c=pool"]
27+
task [URL="?c=task"]
28+
event [URL="?c=event"]
29+
host_cpu [URL="?c=host_cpu"]
30+
host_metrics [URL="?c=host_metrics"]
31+
SM [URL="?c=SM"]
32+
VM_metrics [URL="?c=VM_metrics"]
33+
VM_guest_metrics [URL="?c=VM_guest_metrics"]
34+
console [URL="?c=console"]
35+
PIF_metrics [URL="?c=PIF_metrics"];
1336

1437
edge [arrowhead="none", arrowtail="none"]
1538

‎ocaml/doc/doc-convert.sh‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,10 @@ set -xeu
55
GRAPHVIZ_FLAGS="-Tpng"
66

77
dot vm-lifecycle.dot ${GRAPHVIZ_FLAGS} -o vm-lifecycle.png
8-
dot classes.dot ${GRAPHVIZ_FLAGS} -o classes.png
8+
dot classes.dot ${GRAPHVIZ_FLAGS} -o classes.png -Tcmapx -o classes.map
9+
cp classes.png html
10+
cp classes.png vm-lifecycle.png markdown
11+
sed -e '/@graph_placeholder@/{r classes.map' -e 'd}' -i html/index.html
912

1013
usage() {
1114
echo "Usage:"
@@ -41,6 +44,8 @@ DB_FLAGS="
4144
--template=template.db
4245
"
4346

47+
cd markdown
48+
4449
case "$1" in
4550
--pdf)
4651
pandoc ${FILES} cover.yaml ${PDF_FLAGS}

‎ocaml/doc/index.html‎

Lines changed: 6 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -35,34 +35,9 @@
3535
<div id="container"><div id="content">
3636
<h1 class="title">XenAPI Classes</h1>
3737
<p>Click on a class to view the associated fields and messages.</p>
38-
38+
3939
<img src="classes.png" usemap="#graph" border="0" />
40-
<map id="graph" name="graph">
41-
<area shape="poly" href="?c=task" title="an asynchronous server&#45;side task" alt="" coords="408,233 406,227 402,222 395,217 387,214 378,213 369,214 360,217 354,222 349,227 348,233 349,240 354,245 360,250 369,252 378,253 387,252 395,250 402,245 406,240"/>
42-
<area shape="poly" href="?c=event" title="allows event registration and reading" alt="" coords="408,296 406,289 402,284 395,279 387,277 378,276 369,277 360,279 354,284 349,289 348,296 349,302 354,307 360,312 369,315 378,316 387,315 395,312 402,307 406,302"/>
43-
<area shape="poly" href="?c=pool" title="a Resource Pool" alt="" coords="470,78 469,72 464,66 458,62 449,59 440,58 431,59 422,62 416,66 411,72 410,78 411,84 416,90 422,94 431,97 440,98 449,97 458,94 464,90 469,84"/>
44-
<area shape="rect" href="?c=session" title="an authenticated session" alt="" coords="92,211,152,251"/>
45-
<area shape="rect" href="?c=user" title="a user" alt="" coords="6,201,66,241"/>
46-
<area shape="rect" href="?c=host" title="a physical host" alt="" coords="187,223,247,263"/>
47-
<area shape="rect" href="?c=VM" title="a Virtual Machine" alt="" coords="508,279,568,319"/>
48-
<area shape="poly" href="?c=VM_metrics" title="dynamic VM configuration information" alt="" coords="673,301 671,295 665,289 656,285 644,282 631,281 618,282 607,285 597,289 591,295 589,301 591,307 597,313 607,317 618,320 631,321 644,320 656,317 665,313 671,307"/>
49-
<area shape="poly" href="?c=VM_guest_metrics" title="dynamic information from inside the guest" alt="" coords="670,360 667,354 658,348 645,344 628,341 610,340 592,341 575,344 562,348 553,354 550,360 553,366 562,372 575,376 592,379 610,380 628,379 645,376 658,372 667,366"/>
50-
<area shape="poly" href="?c=crashdump" title="VM crashdump" alt="" coords="650,246 648,239 642,234 633,229 622,227 609,226 596,227 585,229 576,234 570,239 568,246 570,252 576,257 585,262 596,265 609,266 622,265 633,262 642,257 648,252"/>
51-
<area shape="poly" href="?c=console" title="location information for a guest&#39;s console" alt="" coords="590,387 589,380 584,375 577,370 569,368 559,367 549,368 540,370 533,375 529,380 527,387 529,393 533,398 540,403 549,406 559,407 569,406 577,403 584,398 589,393"/>
52-
<area shape="rect" href="?c=PBD" title="the connection between an SR and a host" alt="" coords="244,147,304,187"/>
53-
<area shape="poly" href="?c=host_metrics" title="dynamic host information" alt="" coords="202,307 199,300 193,295 183,290 170,288 156,287 141,288 128,290 118,295 112,300 109,307 112,313 118,318 128,323 141,326 156,327 170,326 183,323 193,318 199,313"/>
54-
<area shape="poly" href="?c=host_cpu" title="a physical CPU on a host" alt="" coords="206,164 204,158 199,153 191,148 182,145 171,144 160,145 151,148 143,153 138,158 136,164 138,171 143,176 151,181 160,183 171,184 182,183 191,181 199,176 204,171"/>
55-
<area shape="rect" href="?c=network" title="an ethernet network" alt="" coords="331,331,391,371"/>
56-
<area shape="rect" href="?c=VIF" title="a network interface for a Virtual Machine" alt="" coords="423,334,483,374"/>
57-
<area shape="poly" href="?c=VIF_metrics" title="IO stats and configuration information for a virtual interface" alt="" coords="498,451 496,445 490,439 481,435 470,432 457,431 444,432 432,435 423,439 417,445 415,451 417,457 423,463 432,467 444,470 457,471 470,470 481,467 490,463 496,457"/>
58-
<area shape="rect" href="?c=PIF" title="a network interface for a physical host" alt="" coords="241,306,301,346"/>
59-
<area shape="poly" href="?c=PIF_metrics" title="IO stats and configuration information for a physical interface" alt="" coords="274,412 272,406 266,400 257,396 245,393 232,392 219,393 208,396 198,400 193,406 191,412 193,418 198,424 208,428 219,431 232,432 245,431 257,428 266,424 272,418"/>
60-
<area shape="rect" href="?c=SR" title="Storage Repository, a container for virtual disk images (VDIs)" alt="" coords="323,97,383,137"/>
61-
<area shape="rect" href="?c=VDI" title="a virtual disk image" alt="" coords="412,124,472,164"/>
62-
<area shape="poly" href="?c=SM" title="storage manager plugin module" alt="" coords="377,26 375,19 371,14 364,9 356,7 347,6 337,7 329,9 322,14 318,19 317,26 318,32 322,37 329,42 337,45 347,46 356,45 364,42 371,37 375,32"/>
63-
<area shape="rect" href="?c=VBD" title="a virtual block device" alt="" coords="486,181,546,221"/>
64-
<area shape="poly" href="?c=VBD_metrics" title="IO stats and configuration information for a virtual block device" alt="" coords="623,128 620,122 614,116 604,112 592,109 578,108 564,109 551,112 541,116 535,122 533,128 535,134 541,140 551,144 564,147 578,148 592,147 604,144 614,140 620,134"/>
65-
</map>
40+
@graph_placeholder@
6641
<h1>Classes, Fields and Messages</h1>
6742
<p>Classes have both <i>fields</i> and <i>messages.</i> Messages are either <i>implicit</i> or <i>explicit</i> where an implicit message is one of:</p>
6843
<ul>
@@ -78,11 +53,11 @@ <h1>Classes, Fields and Messages</h1>
7853
<ul>
7954
<li> set_X: change the value of field X (only if it is read-write);</li>
8055
<li> get_X: retrieve the value of field X;</li>
81-
<li> add_to_X: add a key/value pair (only if field has type set or map); and</li>
82-
<li> remove_from_X: remove a key (only if a field has type set or map).</li>
56+
<li> add_X: add a new element (only if a field has type set);</li>
57+
<li> remove_X: remove an element (only if a field has type set);</li>
58+
<li> add_to_X: add a key-value pair (only if a field has type map); and</li>
59+
<li> remove_from_X: remove a key (only if a field has type map).</li>
8360
</ul>
84-
85-
</p>
8661
</div></div>
8762
<div id="sidebar"></div>
8863
<div id="footer"></div>

‎ocaml/idl/markdown_backend.ml‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -137,9 +137,8 @@ let markdown_section_of_message printer ~is_class_deprecated ~is_class_removed x
137137
printer "_Signature:_";
138138
printer "";
139139
printer "```";
140-
printer (of_ty_opt_verbatim x.msg_result);
141-
printer (sprintf "%s (%s)"
142-
x.msg_name
140+
printer (sprintf "%s %s (%s)"
141+
(of_ty_opt_verbatim x.msg_result) x.msg_name
143142
(String.concat ", "
144143
((if x.msg_session then ["session ref session_id"] else []) @
145144
(List.map (fun p -> of_ty_verbatim p.param_type ^ " " ^ p.param_name) x.msg_params)))

0 commit comments

Comments
 (0)