forked from jsdoc/jsdoc.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
about-tutorials.html
171 lines (168 loc) · 7.27 KB
/
about-tutorials.html
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
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="Adding tutorials to your API documentation.">
<title>Use JSDoc: Tutorials</title>
<link rel="stylesheet" href="styles/usejsdoc.css">
<link rel="stylesheet" href="styles/prettify.css">
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
<script src="scripts/prettify.js"></script>
</head>
<body>
<header>
<a href="./index.html">@use JSDoc</a>
</header>
<article>
<h1>Tutorials</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#adding-tutorials">Adding tutorials</a>
</li>
<li>
<a href="#configuring-titles-order-and-hierarchy">Configuring titles, order, and hierarchy</a>
</li>
<li>
<a href="#linking-to-tutorials-from-api-documentation">Linking to tutorials from API documentation</a>
<ul>
<li>
<a href="#tutorial-block-tag">@tutorial block tag</a>
</li>
<li>
<a href="#tutorial-inline-tag">{@tutorial} inline tag</a>
</li>
</ul>
</li>
</ul>
<p>JSDoc allows you to include tutorials alongside your API documentation. You can use this feature to
provide detailed instructions for using your API, such as a "getting started" guide or a
step-by-step process for implementing a feature.</p>
<h2 id="adding-tutorials">Adding tutorials</h2>
<p>To add tutorials to your API documentation, run JSDoc with the <code>--tutorials</code> or <code>-u</code> option, and
provide a directory that JSDoc should search for tutorials. For example:</p>
<pre class="prettyprint"><code>jsdoc -u path/to/tutorials path/to/js/files
</code></pre>
<p>JSDoc searches the tutorials directory for files with the following extensions:</p>
<ul>
<li><code>.htm</code></li>
<li><code>.html</code></li>
<li><code>.markdown</code> (converted from Markdown to HTML)</li>
<li><code>.md</code> (converted from Markdown to HTML)</li>
<li><code>.xhtml</code></li>
<li><code>.xml</code> (treated as HTML)</li>
</ul>
<p>JSDoc also searches for JSON files that contain information about the titles, ordering, and
hierarchy of your tutorials, as discussed in the following section.</p>
<p>JSDoc assigns an identifier to each tutorial. The identifier is the filename without its extension.
For example, the identifier for <code>/path/to/tutorials/overview.md</code> is <code>overview</code>.</p>
<p>In tutorial files, you can use the <a href="tags-inline-link.html"><code>{@link}</code></a> and
<a href="tags-inline-tutorial.html"><code>{@tutorial}</code></a> inline tags to link to other parts of the documentation. JSDoc
will automatically resolve the links.</p>
<h2 id="configuring-titles-order-and-hierarchy">Configuring titles, order, and hierarchy</h2>
<p>By default, JSDoc uses the filename as the tutorial's title, and all tutorials are at the same
level. You can use a JSON file to provide a title for each tutorial and indicates how the tutorials
should be sorted and grouped in the documentation.</p>
<p>The JSON file must use the extension <code>.json</code>. In the JSON file, you can use the tutorial identifiers
to provide two properties for each tutorial:</p>
<ul>
<li><code>title</code>: The title to display in the documentation.</li>
<li><code>children</code>: The children of the tutorial.</li>
</ul>
<p>In JSDoc 3.2.0 and later, you can use the following formats for the JSON file:</p>
<ol>
<li>
<p>A tree of objects, with child tutorials defined in the <code>children</code> property of their parent.
For example, if <code>tutorial1</code> has two children, <code>childA</code> and <code>childB</code>, and <code>tutorial2</code> is at the same
level as <code>tutorial1</code> and has no children:</p>
<pre class="prettyprint lang-json"><code> {
"tutorial1": {
"title": "Tutorial One",
"children": {
"childA": {
"title": "Child A"
},
"childB": {
"title": "Child B"
}
}
},
"tutorial2": {
"title": "Tutorial Two"
}
}
</code></pre>
</li>
<li>
<p>A top-level object whose properties are all tutorial objects, with child tutorials listed by name
in an array. For example, if <code>tutorial1</code> has two children, <code>childA</code> and <code>childB</code>, and <code>tutorial2</code> is
at the same level as <code>tutorial1</code> and has no children:</p>
<pre class="prettyprint lang-json"><code> {
"tutorial1": {
"title": "Tutorial One",
"children": ["childA", "childB"]
},
"tutorial2": {
"title": "Tutorial Two"
},
"childA": {
"title": "Child A"
},
"childB": {
"title": "Child B"
}
}
</code></pre>
</li>
</ol>
<p>You can also provide an individual <code>.json</code> file for each tutorial, using the tutorial identifier as
the filename. This method is deprecated and should not be used for new projects.</p>
<h2 id="linking-to-tutorials-from-api-documentation">Linking to tutorials from API documentation</h2>
<p>There are multiple ways to link to a tutorial from your API documentation:</p>
<h3 id="tutorial-block-tag">@tutorial block tag</h3>
<p>If you include a <a href="tags-tutorial.html"><code>@tutorial</code> block tag</a> in a JSDoc comment, the generated documentation
will include a link to the tutorial you specify.</p>
<figure>
<figcaption>Using the <code>@tutorial</code> block tag</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Class representing a socket connection.
*
* @class
* @tutorial socket-tutorial
*/
function Socket() {}
</code></pre>
</figure>
<h3 id="tutorial-inline-tag">{@tutorial} inline tag</h3>
<p>You can also use the <a href="tags-inline-tutorial.html"><code>{@tutorial}</code> inline tag</a> to link to a tutorial within the text
of another tag. By default, JSDoc will use the tutorial's title as the link text.</p>
<figure>
<figcaption>Using the <code>{@tutorial}</code> inline tag</figcaption>
<pre class="prettyprint lang-js"><code>/**
* Class representing a socket connection. See {@tutorial socket-tutorial}
* for an overview.
*
* @class
*/
function Socket() {}
</code></pre>
</figure>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br>
Copyright © 2011-2017 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the
JSDoc 3 documentation project.
<br>
This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is
licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
</footer>
<script type="text/javascript">
prettyPrint();
</script>
</body>
</html>