This project serves as a utility wrapper for JSDoc.
This package provides the following advantages over using JSDoc by itself:
- provides ready made configuration that is ready to use out of the box
- is integrated with
git
and GitHub Pages
Simply run npm run docPublish
to create a gh-pages
branch in your repository, generate the documentation from your source, and push it to GitHub. After that all you need to do is find the link under <Project> -> Settings -> GitHub Pages
and make it the project website link on the projects home page in GitHub. See the Usage section for more details.
This project will take your README.md
file and turn it into a homepage with links to the documentation from your source code as defined by JSDoc. See jsdocgenTest as an example.
npm install -g jsdoc
JSDoc cannot be used as library and must be installed globally.
Add the following snippets to your package.json
file:
{
"devDependencies": {
"jsdocgen": "^0.2.1"
}
}
{
"devDependencies": {
"jsdocgen": "git+https://github.com/h2oboi89/jsdocgen.git#<commit-ish>"
}
}
<commit-ish>
can be any tag, sha, or branch. Default is nothing (master
). See here for more information.
Commit-ish | Example |
---|---|
Nothing | .../jsdocgen.git |
Branch | .../jsdocgen.git#master |
Tag | .../jsdocgen.git#v0.2.0 |
SHA | .../jsdocgen.git#3fbba539739989842d8fbf86ee90bbfbd5cd9ef5 |
NOTE: First two examples are functionally identical.
{
"scripts": {
"docClone": "jsdocgen clone",
"docGenerate": "jsdocgen generate",
"docPublish": "jsdocgen publish"
}
}
These provide a means of running jsdocgen
. See Usage for more details.
{
"repository": {
"type": "git",
"url": "<repo SSH link>"
}
}
This is how jsdocgen
will know where to put the documentation.
Get the <repo SSH link>
by copying the URL provided by GitHub SSH clone URL
.
Example: git@github.com:h2oboi89/jsdocgenTest.git
NOTE: you can use the HTTP clone URL
if you so desire, but we recommend the SSH clone URL
instead.
From your project root call the following via npm run <Command>
:
Command | Result |
---|---|
docClone |
clones the project repository into ./doc/ and checks out the gh-pages branch |
docGenerate |
generates the documentation using JSDoc |
docPublish |
pushes updated documentation to origin:gh-pages |
NOTE: each step will automatically call the preceding step (docPublish -> docGenerate -> docClone
)
You can tweak the JSDoc settings by modifying jsdoc.json.
You can tweak the GitHub
integration by modifying the files found in ./src
.
The jsdocgenTest repository serves as a means to test this project and also provides some examples on how to use JSDoc.