hsdocs
v2.9.2
Published
Helpful Scripts API documentation viewer for Typescript projects
Downloads
36
Maintainers
masterscripterReadme
hsDocs
Helpful Scripts code documentation tool.
hsDocs is an alternative code documentation viewer for Typescript projects. It renders JSON documentation files, as created by typedoc, into html pages that can be viewed via browser. This example shows the rendered docset for the hsDoc code itself.
Features
Provides a more compact overview of Typescript library documentation as an alternative to Typedoc ...
- facilitating live, interactive code examples in the docs to illustrate functionality and usage
- allowing display of multiple libraries via tabs
Usage
1 - Create a web-app directory to serve the docsets from. As an example,
see the docs folder in this project's Github page, which serves the Github IO pages for this project
2a - Copy the index.html file from Github into the new directory,
or create a new index.html as follows. This will use the GitHub-hosted version of hsDocs:
<html>
<head>
<link href="https://helpfulscripts.github.io/hsDocs/hsDocs.css" rel="stylesheet" />
</head>
<body class='hs-layout-fill'>
<script src="https://helpfulscripts.github.io/hsDocs/hsDocs.min.js"></script>
</body>
</html>2b - Alternatively you can use a self-hosted hsDocs version. Copy the hsDocs runtimes
(hsDocs.js, hsDocs.min.js, hsDocs.css, hsDocs.css.map) from
Github into the directory and modify index.html as follows:
<html>
<head><link href="hsDocs.css" rel="stylesheet" /></head>
<body class='hs-layout-fill'>
<script src="./hsDocs.min.js"></script>
</body>
</html>3 - Install typedoc and, inside your project folder, run
typedoc --json docs.json src
(or: ./node_modules/.bin/typedoc --json docs.json src)in your project folder. This assumes src is the path to the sources the sources.
Create a subdirectory ./data and copy the docset into it - i.e. docs.json if you used the
commend above.
See below for more details on creating the docset.
4 - Create a list of docsets to render in a new file index.json inside ./data.
Files in the docs array are interpreted relative to the ./data folder unless they are full URLs.
{ "docs": [
"docs.json",
"http://helpfulscripts.github.io/hsLayout/data/hsLayout.json",
...
],
"title": "HS Libraries" // will be displayed at the top left corner
}5 - optionally, create a src folder inside the data folder and copy the html-ified source files into it.
These are created by the command grunt sourceCode in the docs/data/src/ folder of your project.
6 - Point a browser to the web-app directory
Creating the Documentation DocSet
Follow the instruction for typedoc in commenting the code
and set the json option to create a
json file containing the documentation. See the Configuration section below for details.
In addition to the documented source files, hsDocs recognizes a special overview.ts file
that will be displayed as a project overview.
For this to work, typedoc requires the file to have two separate comment entries.
If the second comment is missing, typedoc will not generate a comment in the DocSet.
DocSets are shown as menu tabs across the top of the window. To include a DocSet in the menu, ensure that the
corresponding documentation .json file is copied into the data folder inside the hsDocs staging location
for the http server. Then edit the index.json file to include the documentation file name in the "docs" section.
See hsDocs/docs/data fro an example.
Installation
Install hsDocs from npm the standard way:
npm i hsdocs
Typedoc configuration
Below is an example configuration for use with grunt and grunt-typedoc:
typedoc: {
code: {
options: {
target: 'es6',
module: 'commonjs',
moduleResolution: "node",
json: `docs/data/myLib.json`,
mode: 'modules',
name: `myLib`
},
src: ['src/**/*.ts', '!src/**/*.*.ts'] // all .ts files, no specs
}
}Please see the docs for further documentation and examples
Please report any issues and provide feedback.