1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
This document describes the structure of the HTML generated by the renderapi.py
tool, both for use in the API docs shown by "cfx docs" and as exported by
"cfx sdocs". The particular HTML id and class attributes embedded in the files,
as well as their organization, represent the interface between the tool and any
front-end code wanting to style the docs in some particular way.
renderapi generates two sorts of files:
- a file called "<module-name>.div": this is the contents of the parsed
Markdown file rendered inside a well-defined DIV tag
- a file called "<module-name>.html": this is the DIV from above inserted into
a simple HTML template that references a sample CSS file which styles the
contents of the DIV. This CSS file is the same as the one used by the SDK
itself.
DIV tags
--------
The following class and id attributes are used in the DIV:
renderapi uses a number of class attributes and a single id attribute in the DIV:
id attribute <module_name>"_module_api_docs"
class attribute "api_reference"
class attribute "module_api_docs"
class attribute "api_header"
class attribute "api_name"
class attribute "api_component_group"
class attribute "api_component"
class attribute "datatype"
class attribute "returns"
class attribute "parameter_set"
class attribute "module_description"
DIV structure
-------------
The top level DIV is marked with the id attribute and the "module_api_docs" class
attribute:
<div id='tabs_module_api_docs' class='module_api_docs'>
//module doc contents
</div>
Inside this:
- the first item is an <h1> heading containing the name of the module:
- all "markdown" hunks (that is, all descriptive text not occurring
inside <api></api> tags) are rendered inside a DIV marked with the
"module-description" class attribute
- all <api></api> content is rendered, enclosed in a single tag marked
with the "api_reference" class attribute:
<div id='tabs_module_api_docs' class='module_api_docs'>
<div class='module_description'>
//descriptions
</div>
<div class='api_reference'>
//api reference
</div>
</div>
If there is no <api></api> content, then the "api-reference" section is absent.
### API Reference structure ###
The first item in API reference is an <h2> heading title marked with the
"api_header" attribute. This might have the text content "API Reference"
(but you should not rely on that):
<div class='api_reference'>
<h2 class='api_header'>API Reference</h2>
//api contents
</div>
After the title come one or more component groups.
#### Component Group ####
A component group is marked with the "api_component_group" attribute. The
component group is a collection of some sort of component: for example, a group
of classes, a group of functions, or a group of events.
Each component group starts off with a header marked with the
"api_header" attribute and is followed by one or more sections marked with the
"api_component" attribute.
At the top level (that is, when they are directly under the "API Reference"
heading), the "api_header" items are <h3> headings, otherwise they are divs.
<div class='api_reference'>
<h2 class='api_header'>API Reference</h2>
<div class='api_component_group'>
<h3 class='api_header'>Classes</h3>
<div class='api_component'>
// the first class
</div>
<div class='api_component'>
// another class
</div>
</div>
<div class='api_component_group'>
//some different components
<h3 class='api_header'>Functions</h3>
<div class='api_component'>
the first function
</div>
<div class='api_component'>
another function
</div>
</div>
</div>
#### Component ####
API components represent actual objects in the API like classes, functions,
properties and events.
Each component starts with a section marked with the
"api_name" tag, which includes the name of the component in the API: for
example "postMessage(message)".
Components at the top level (i.e., directly under h3 headings) are <h4>
headings, otherwise they are divs.
After the name, the component's contents are listed. Different sorts of
components may have different sorts of contents: for example, a function might
have parameters. If the component is composite then it may contain its own
component group. For example, a class may contain methods and properties,
which might be grouped together.
<div class='api_component'>
<h4 class='api_name'>Panel</h4>
<div class='api_component_group'>
<div class='api_header'>
Methods
</div>
<div class='api_component'>
show()
</div>
</div>
</div>
Other attributes
-----------------------------
### Datatype ###
All primitive data types, like "string" and "number", are marked with the
"datatype" class attribute:
<div class="api_component">
<div class="api_name">
label : <span class="datatype">string</span>
</div>
<p>A required string description of the widget used for accessibility,
title bars, and error reporting.</p>
</div>
### Returns ###
Functions mark return values with the "returns" class attribute.
<div class="api_component">
<div class="api_name">
get()
</div>
Make a `GET` request.
<div class="returns">
Returns: <span class="datatype">Request</span>
</div>
</div>
### Parameter_set ###
Functions that take parameters mark them with the parameter_set class
attribute.
|
