Skip to content

Commit 5197e30

Browse files
hegemonichegemonic
committed
update readme page; add package-file page; reorder links on home page (#89)
1 parent 1e0a1c8 commit 5197e30

File tree

6 files changed

+162
-24
lines changed

6 files changed

+162
-24
lines changed

‎about-including-package.html‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
<!DOCTYPE html>
2+
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
3+
<html lang="en">
4+
5+
<head>
6+
<meta charset="utf-8">
7+
<meta name="description" content="How to show package details in your documentation.">
8+
<title>Use JSDoc: Including a Package File</title>
9+
<link rel="stylesheet" href="styles/usejsdoc.css">
10+
<link rel="stylesheet" href="styles/prettify.css">
11+
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
12+
<script src="scripts/prettify.js"></script>
13+
<!--[if lt IE 9]>
14+
<script src="scripts/html5shiv.min.js"></script>
15+
<script src="scripts/html5shiv-printshiv.min.js"></script>
16+
<![endif]-->
17+
</head>
18+
19+
<body>
20+
<header>
21+
<a href="./index.html">@use JSDoc</a>
22+
</header>
23+
<article>
24+
<h1>Including a Package File</h1>
25+
<p>Package files contain information that can be useful for your project&#39;s documentation, such as the project&#39;s name and version number. JSDoc can automatically
26+
use information from your project&#39;s
27+
<code>package.json</code> file when it generates documentation. For example, the default template shows the project&#39;s name and version number in the documentation.</p>
28+
<p>There are two ways to incorporate a <code>package.json</code> file into your documentation:</p>
29+
<ol>
30+
<li>In the source paths to your JavaScript files, include the path to a <code>package.json</code> file. JSDoc will use the first <code>package.json</code> file
31+
that it finds in your source paths.</li>
32+
<li>Run JSDoc with the <code>-P/--package</code> command-line option, specifying the path to your <code>package.json</code> file. This option is available in JSDoc
33+
3.3.0 and later.</li>
34+
</ol>
35+
<p>The <code>-P/--package</code> command-line option takes precedence over your source paths. If you use the
36+
<code>-P/--package</code> command-line option, JSDoc will ignore any <code>package.json</code> files in your source paths.</p>
37+
<p>The <code>package.json</code> file must use <a href="https://docs.npmjs.com/files/package.json">npm&#39;s package format</a>.</p>
38+
<h2 id="examples">Examples</h2>
39+
<figure>
40+
<figcaption>Including a package file in your source paths</figcaption><pre class="prettyprint"><code>jsdoc path/to/js path/to/package/package.json
41+
</code></pre>
42+
</figure>
43+
<figure>
44+
<figcaption>Using the -P/--package option</figcaption><pre class="prettyprint"><code>jsdoc --package path/to/package/package-docs.json path/to/js
45+
</code></pre>
46+
</figure>
47+
</article>
48+
<footer>
49+
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
50+
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
51+
</a>
52+
<br> Copyright &#169; 2011-2014 the
53+
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
54+
<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/">
55+
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
56+
</footer>
57+
<script type="text/javascript">
58+
prettyPrint();
59+
</script>
60+
</body>
61+
62+
</html>

‎about-including-readme.html‎

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44

55
<head>
66
<meta charset="utf-8">
7-
<meta name="description" content="A guide to including a readme file in your documentation.">
8-
<title>Use JSDoc: Including a Readme File With JSDoc 3</title>
7+
<meta name="description" content="How to include a README file in your documentation.">
8+
<title>Use JSDoc: Including a README File</title>
99
<link rel="stylesheet" href="styles/usejsdoc.css">
1010
<link rel="stylesheet" href="styles/prettify.css">
1111
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
@@ -21,15 +21,26 @@
2121
<a href="./index.html">@use JSDoc</a>
2222
</header>
2323
<article>
24-
<h1>Including a Readme File With JSDoc 3</h1>
25-
<p>To include a readme file in your documentation, you simply specify the location of your readme file on the command line along with the location of your source
26-
files. The readme file will be incorporated into the index.html of your documentation in the default template. The file must be written in markdown and given
27-
a .md extension.</p>
24+
<h1>Including a README File</h1>
25+
<p>There are two ways to incorporate a <code>README</code> file into your documentation:</p>
26+
<ol>
27+
<li>In the source paths to your JavaScript files, include the path to a Markdown file named
28+
<code>README.md</code>. JSDoc will use the first <code>README.md</code> file that it finds in your source paths.</li>
29+
<li>Run JSDoc with the <code>-R/--readme</code> command-line option, specifying the path to your <code>README</code> file. This option is available in JSDoc 3.3.0
30+
and later. The <code>README</code> file may have any name and extension, but it must be in Markdown format.</li>
31+
</ol>
32+
<p>The <code>-R/--readme</code> command-line option takes precedence over your source paths. If you use the
33+
<code>-R/--readme</code> command-line option, JSDoc will ignore any <code>README.md</code> files in your source paths.</p>
34+
<p>If you are using JSDoc&#39;s default template, the <code>README</code> file&#39;s contents will be rendered in HTML in the generated documentation&#39;s <code>index.html</code> file.</p>
35+
<h2 id="examples">Examples</h2>
2836
<figure>
29-
<figcaption>Including a readme file in your documentation</figcaption><pre class="prettyprint"><code>jsdoc C:\path\to\my\JS\project\sourceFiles C:\path\to\my\JS\project\README.md
37+
<figcaption>Including a README file in your source paths</figcaption><pre class="prettyprint"><code>jsdoc path/to/js path/to/readme/README.md
38+
</code></pre>
39+
</figure>
40+
<figure>
41+
<figcaption>Using the -R/--readme option</figcaption><pre class="prettyprint"><code>jsdoc --readme path/to/readme/README path/to/js
3042
</code></pre>
3143
</figure>
32-
<p>If your file is successfully incorporated into the default template, it&#39;s content will be rendered in beautiful HTML just before the files list.</p>
3344
</article>
3445
<footer>
3546
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">

‎content/en/about-including-package.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Including a Package File
3+
description: How to show package details in your documentation.
4+
---
5+
6+
Package files contain information that can be useful for your project's documentation, such as
7+
the project's name and version number. JSDoc can automatically use information from your project's
8+
`package.json` file when it generates documentation. For example, the default template shows
9+
the project's name and version number in the documentation.
10+
11+
There are two ways to incorporate a `package.json` file into your documentation:
12+
13+
1. In the source paths to your JavaScript files, include the path to a `package.json` file. JSDoc
14+
will use the first `package.json` file that it finds in your source paths.
15+
2. Run JSDoc with the `-P/--package` command-line option, specifying the path to your `package.json`
16+
file. This option is available in JSDoc 3.3.0 and later.
17+
18+
The `-P/--package` command-line option takes precedence over your source paths. If you use the
19+
`-P/--package` command-line option, JSDoc will ignore any `package.json` files in your source paths.
20+
21+
The `package.json` file must use [npm's package format][package-json].
22+
23+
[package-json]: https://docs.npmjs.com/files/package.json
24+
25+
26+
## Examples
27+
28+
{% example "Including a package file in your source paths" %}
29+
30+
```
31+
jsdoc path/to/js path/to/package/package.json
32+
```
33+
{% endexample %}
34+
35+
{% example "Using the -P/--package option" %}
36+
37+
```
38+
jsdoc --package path/to/package/package-docs.json path/to/js
39+
```
40+
{% endexample %}

‎content/en/about-including-readme.md‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,35 @@
11
---
2-
title: Including a Readme File With JSDoc 3
3-
description: A guide to including a readme file in your documentation.
2+
title: Including a README File
3+
description: How to include a README file in your documentation.
44
---
55

6-
To include a readme file in your documentation, you simply specify the location of your readme file on the command line along with the location of your source files. The readme file will be incorporated into the index.html of your documentation in the default template. The file must be written in markdown and given a .md extension.
6+
There are two ways to incorporate a `README` file into your documentation:
77

8-
{% example "Including a readme file in your documentation" %}
8+
1. In the source paths to your JavaScript files, include the path to a Markdown file named
9+
`README.md`. JSDoc will use the first `README.md` file that it finds in your source paths.
10+
2. Run JSDoc with the `-R/--readme` command-line option, specifying the path to your `README` file.
11+
This option is available in JSDoc 3.3.0 and later. The `README` file may have any name and
12+
extension, but it must be in Markdown format.
13+
14+
The `-R/--readme` command-line option takes precedence over your source paths. If you use the
15+
`-R/--readme` command-line option, JSDoc will ignore any `README.md` files in your source paths.
16+
17+
If you are using JSDoc's default template, the `README` file's contents will be rendered in HTML
18+
in the generated documentation's `index.html` file.
19+
20+
21+
## Examples
22+
23+
{% example "Including a README file in your source paths" %}
924

1025
```
11-
jsdoc C:\path\to\my\JS\project\sourceFiles C:\path\to\my\JS\project\README.md
26+
jsdoc path/to/js path/to/readme/README.md
1227
```
1328
{% endexample %}
1429

15-
If your file is successfully incorporated into the default template, it's content will be rendered in beautiful HTML just before the files list.
30+
{% example "Using the -R/--readme option" %}
31+
32+
```
33+
jsdoc --readme path/to/readme/README path/to/js
34+
```
35+
{% endexample %}

‎data/toc.json‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,6 @@
66
{
77
"filename": "about-namepaths.html"
88
},
9-
{
10-
"filename": "about-tutorials.html"
11-
},
12-
{
13-
"filename": "about-including-readme.html"
14-
},
159
{
1610
"filename": "about-commandline.html"
1711
},
@@ -27,6 +21,15 @@
2721
{
2822
"filename": "plugins-markdown.html"
2923
},
24+
{
25+
"filename": "about-tutorials.html"
26+
},
27+
{
28+
"filename": "about-including-package.html"
29+
},
30+
{
31+
"filename": "about-including-readme.html"
32+
},
3033
{
3134
"filename": "about-license-jsdoc3.html"
3235
}

‎index.html‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,6 @@ <h2>Getting Started</h2>
2828
<dd>A quick-start to documenting JavaScript with JSDoc.</dd>
2929
<dt><a href="about-namepaths.html">Using namepaths with JSDoc 3</a></dt>
3030
<dd>A guide to using namepaths with JSDoc 3.</dd>
31-
<dt><a href="about-tutorials.html">Tutorials</a></dt>
32-
<dd>Adding tutorials to your API documentation.</dd>
33-
<dt><a href="about-including-readme.html">Including a Readme File With JSDoc 3</a></dt>
34-
<dd>A guide to including a readme file in your documentation.</dd>
3531
<dt><a href="about-commandline.html">Command-line arguments to JSDoc</a></dt>
3632
<dd>About command-line arguments to JSDoc.</dd>
3733
<dt><a href="about-configuring-jsdoc.html">Configuring JSDoc with conf.json</a></dt>
@@ -42,6 +38,12 @@ <h2>Getting Started</h2>
4238
<dd>How to create and use JSDoc plugins.</dd>
4339
<dt><a href="plugins-markdown.html">Using the Markdown plugin</a></dt>
4440
<dd>Enable Markdown support in JSDoc.</dd>
41+
<dt><a href="about-tutorials.html">Tutorials</a></dt>
42+
<dd>Adding tutorials to your API documentation.</dd>
43+
<dt><a href="about-including-package.html">Including a Package File</a></dt>
44+
<dd>How to show package details in your documentation.</dd>
45+
<dt><a href="about-including-readme.html">Including a README File</a></dt>
46+
<dd>How to include a README file in your documentation.</dd>
4547
<dt><a href="about-license-jsdoc3.html">License</a></dt>
4648
<dd>License information for JSDoc 3.</dd>
4749
</dl>

0 commit comments

Comments
 (0)