README

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.

Usage no npm install needed!