# overview.ts

`

1<comment>/**</comment>

2<comment># hsDocs</comment>

3<comment></comment>

4<comment>Helpful Scripts code documentation viewer. </comment>

5<comment><a href=<quote>"./data/src/hsDocs/coverage/"</quote> target=<quote>"_blank"</quote>>[Coverage Info]</comment>

6<comment></comment>

7<comment>[![npm version](https:<comment>//badge.fury.io/js/hsdocs.svg)](https://badge.fury.io/js/hsdocs)</comment></comment>

8<comment><comment></comment>[![GitHub](https:<comment>//img.shields.io/badge/GitHub-hsDocs-blue.svg)](https://github.com/helpfulscripts/hsdocs)</comment></comment>

9<comment><comment></comment>[![docs](https:<comment>//img.shields.io/badge/hsDocs-hsDocs-blue.svg)](https://helpfulscripts.github.io/hsDocs/#!/api/hsDocs/0)</comment></comment>

10<comment><comment></comment>[![Build Status](https:<comment>//travis-ci.org/HelpfulScripts/hsDocs.svg?branch=master)](https://travis-ci.org/HelpfulScripts/hsDocs)</comment></comment>

11<comment><comment></comment>[![Dependencies Status](https:<comment>//david-dm.org/helpfulscripts/hsdocs.svg)](https://david-dm.org/helpfulscripts/hsdocs)</comment></comment>

12<comment><comment></comment>[![codecov](https:<comment>//codecov.io/gh/HelpfulScripts/hsDocs/branch/master/graph/badge.svg)](https://codecov.io/gh/HelpfulScripts/hsDocs)</comment></comment>

13<comment><comment></comment>[![Known Vulnerabilities](https:<comment>//snyk.io/test/github/HelpfulScripts/hsDocs/badge.svg?targetFile=package.json)](https://snyk.io/test/github/HelpfulScripts/hsDocs?targetFile=package.json)</comment></comment>

14<comment><comment></comment>[![NPM License](https:<comment>//img.shields.io/badge/license-MIT-brightgreen.svg)](https://www.npmjs.com/package/hsdocs)</comment></comment>

15<comment><comment></comment></comment>

16<comment>___</comment>

17<comment>hsDocs.js is a code documentation viewer for [Typescript](https:<comment>//www.typescriptlang.org) projects.</comment></comment>

18<comment><comment></comment>It provides a browser rendering of JSON documentation files as created by [typedoc](http:<comment>//typedoc.org).</comment></comment>

19<comment><comment></comment></comment>

20<comment>## Usage</comment>

21<comment>1 - Create a web-app directory to serve the docsets from. As an example, </comment>

22<comment>see the `docs` folder in this project<quote>'s [Github page](https:<comment>//github.com/HelpfulScripts/hsDocs/tree/master/docs), </comment></comment>

23<comment><comment></comment>which serves the [Github IO pages for this project](https:<comment>//helpfulscripts.github.io/hsDocs/#!/api/hsDocs/0)</comment></comment>

24<comment><comment></comment></comment>

25<comment>2a - Copy the `index.html` file from [Github](https:<comment>//github.com/HelpfulScripts/hsDocs/tree/master/docs), </comment></comment>

26<comment><comment></comment>or create a new **`index.html`** as follows. This will use the `GitHub`-hosted version of `hsDocs`:</comment>

27<comment>```</comment>

28<comment>
</comment>

29<comment> </comment>

30<comment> <link href=<quote>"https:<comment>//helpfulscripts.github.io/hsDocs/hsDocs.css"</quote> rel=<quote>"stylesheet"</quote> /></comment></comment>

31<comment><comment></comment> </comment>

32<comment> <body class='</quote>hs-layout-fill<quote>'></comment>

33<comment> <script src=<quote>"https:<comment>//helpfulscripts.github.io/hsDocs/hsDocs.min.js"</quote>></comment></comment>

34<comment><comment></comment>

`
</comment>

35<comment></comment>

36<comment>```</comment>

37<comment></comment>

38<comment>2b - Alternatively you can use a self-hosted hsDocs version. Copy the `hsDocs` runtimes </comment>

39<comment>(`hsDocs.js`, `hsDocs.min.js`, `hsDocs.css`, `hsDocs.css.map`) from</comment>

40<comment>[Github](https:<comment>//github.com/HelpfulScripts/hsDocs/tree/master/docs) into the directory and modify `index.html` as follows:</comment></comment>

41<comment><comment></comment>```</comment>

42<comment>
</comment>

43<comment> <link href=<quote>"hsDocs.css"</quote> rel=<quote>"stylesheet"</quote> /></comment>

44<comment> <body class='</quote>hs-layout-fill<quote>'></comment>

45<comment> <script src=<quote>"./hsDocs.min.js"</quote>></comment>

46<comment> </comment>

47<comment></comment>

48<comment>```</comment>

49<comment></comment>

50<comment>3 - Create a subdirectory **`data`** and copy the docsets into it, for example **`hsDocs.json`** or your project'</quote>s `.json` .</comment>

51<comment>See below for creating the docset.</comment>

52<comment></comment>

53<comment>4 - Create a list of docsets to render in a new file **`index.json`** inside **`data`**:</comment>

54<comment>```</comment>

55<comment>{ </comment>

56<comment> <quote>"docs"</quote>: [</comment>

57<comment> <quote>"hsDocs.json"</quote>,</comment>

58<comment> ...</comment>

59<comment> ],</comment>

60<comment> <quote>"title"</quote>: <quote>"HS Libraries"</quote> <comment>// will be displayed at the top left corner</comment></comment>

61<comment><comment></comment>}</comment>

62<comment>```</comment>

63<comment></comment>

64<comment>5 - optionally, create a `src` folder inside the `data` folder and copy the `html`-ified source files into it. </comment>

65<comment>These are created by the command `grunt sourceCode` in the `docs/data/src/` folder of your project.</comment>

66<comment></comment>

67<comment>6 - Point a browser to the web-app directory</comment>

68<comment></comment>

69<comment>## Creating the Documentation DocSet</comment>

70<comment>Follow the instruction for `typedoc` in commenting the code and set the `json` option to create a </comment>

71<comment>json file containing the documentation. See the Configuration section below for details.</comment>

72<comment></comment>

73<comment>In addition to the documented source files, `hsDocs` recognizes a special **`overview.ts`** file </comment>

74<comment>that will be displayed as a project overview. </comment>

75<comment>For this to work, `typedoc` requires the file to have two separate comment entries.</comment>

76<comment>If the second comment is missing, `typedoc` will not generate a comment in the DocSet.</comment>

77<comment></comment>

78<comment>DocSets are shown as menu tabs across the top of the window. To include a DocSet in the menu, ensure that the </comment>

79<comment>corresponding documentation `<DocSet>.json` file is copied into the `data` folder inside the folder that holds the serving html file.</comment>

80<comment>Then edit the `index.json` file to include the documentation file name in the <quote>"docs"</quote> section. If no `index.json` file is found, </comment>

81<comment>`hsDocs` will attempt to load a directory listing of the `data` file and include all encountered `*.json` files as DocSet. </comment>

82<comment>This requires enabling the http server to provide a directory listing for the `data` folder.</comment>

83<comment></comment>

84<comment>### Modules</comment>

85<comment>Each source file is considered to be a `module`. Modules are shown in the left-hand overview panel of the main `hsDocs` window.</comment>

86<comment>Alternatively, a `@module` statement in the summary comment at the top of a file will create, or add to, a module of the specified name.</comment>

87<comment>This encourages to separate code into files without cluttering the overview.</comment>

88<comment></comment>

89<comment>### Linking across the docsets</comment>

90<comment>Links to items across the docsets can be placed via a link directive: </comment>

91<comment>- `{@link [docset:]module.item` linked text`}`, </comment>

92<comment></comment>

93<comment>where</comment>

94<comment> - *docset* optional; the name of the docset. If omitted, a link within the current docSet will be created</comment>

95<comment> - *module* is name of the module to link to; </comment>

96<comment> if *module* is `overview`, or unspecified, the link will point to the docset overview page.</comment>

97<comment> - *item* is the name, or period-separated path, of the item within the module. </comment>

98<comment> - *linked text* is displayed with a link to path within module</comment>

99<comment></comment>

100<comment>Examples:</comment>

101<comment>- `{@link overview` this hsDocs overview`}` -> {@link overview this hsDocs overview}</comment>

102<comment>- `{@link hsDocs:` this hsDocs overview`}` -> {@link hsDocs: this hsDocs overview}</comment>

103<comment>- `{@link hsDocs:DocSets.DocSets.add` the `add` function`}` -> {@link hsDocs:DocSets.DocSets.add the `add` function}</comment>

104<comment>- `{@link DocSets.DocSets.add` the `add` function`}` -> {@link DocSets.DocSets.add the `add` function}</comment>

105<comment></comment>

106<comment></comment>

107<comment>### Code Examples</comment>

108<comment> * `hsDocs` supports creating live code examples in comment sections as explained </comment>

109<comment> * in the {@link hsDocs:view.MainExample MainExample overview}. The following example </comment>

110<comment> * renders content using [Mithril](https:<comment>//mithril.js.org/). </comment></comment>

111<comment><comment></comment> * <example></comment>

112<comment> * <file name=<quote>"script.js"</quote>></comment>

113<comment> * let tl = [10, 10];</comment>

114<comment> * </comment>

115<comment> * m.mount(root, {</comment>

116<comment> * view: () => m(<quote>'.myBlock'</quote>, {</comment>

117<comment> * onclick:() => tl = tl.map(i => Math.floor(80*Math.random())), </comment>

118<comment> * style:`top:${tl[0]}%; left:${tl[1]}%;`</comment>

119<comment> * }, m(<quote>''</quote>, <quote>'click me'</quote>))</comment>

120<comment> * })</comment>

121<comment> * </file></comment>

122<comment> * <file name=<quote>"style.css"</quote>></comment>

123<comment> * .myBlock {</comment>

124<comment> * text-align:center;</comment>

125<comment> * color: white;</comment>

126<comment> * background-color: red;</comment>

127<comment> * position:relative;</comment>

128<comment> * width: 20%;</comment>

129<comment> * height: 30%;</comment>

130<comment> * }</comment>

131<comment> * .myBlock div {</comment>

132<comment> * padding-top: 40%;</comment>

133<comment> * }</comment>

134<comment> * </file></comment>

135<comment> * </example></comment>

136<comment></comment>

137<comment>## Configuring typedoc</comment>

138<comment>As an example, we use grunt-typedoc with the following configuration:</comment>

139<comment></comment>

140<comment>### tsconfig.json:</comment>

141<comment>A `tsconfig.json` file seems to be required by typedoc. The file can be empty</comment>

142<comment></comment>

143<comment>### Gruntfile:</comment>

144<comment>`module.exports = function(grunt) {</comment>`

145<comment> ...</comment>

146<comment> typedoc: {</comment>

147<comment> code: {</comment>

148<comment> options: {</comment>

149<comment> tsconfig: <quote>'typedoc.json'</quote>,</comment>

150<comment> json: <quote>'./docs/hsDocs.json'</quote>,</comment>

151<comment> out: <quote>'./docs'</quote>,</comment>

152<comment> mode: <quote>'modules'</quote>,</comment>

153<comment> name: <quote>'hsDocs'</quote></comment>

154<comment> }</comment>

155<comment> src: [<quote>'src/*.ts'</quote>, <quote>'!src/*.spec.ts'</quote>]</comment>

156<comment> }</comment>

157<comment> },</comment>

158<comment></comment>

159<comment> ...</comment>

160<comment> grunt.loadNpmTasks(<quote>'grunt-typedoc'</quote>);</comment>

161<comment> ...</comment>

162<comment> grunt.registerTask(<quote>'doc'</quote>, [<quote>'typedoc'</quote>]);</comment>

163<comment>}</comment>

164<comment></comment>

165<comment></comment>

166<comment>## Dependencies</comment>

167<comment>### For creating the docsets:</comment>

168<comment>- [typedoc](http:<comment>//typedoc.org)</comment></comment>

169<comment><comment></comment></comment>

170<comment>### For rendering the docsets:</comment>

171<comment>- [Mithril](https:<comment>//mithril.js.org)</comment></comment>

172<comment><comment></comment>- [showdown](https:<comment>//github.com/showdownjs/showdown)</comment></comment>

173<comment><comment></comment>- [hsLayout](https:<comment>//github.com/HelpfulScripts/hsLayout)</comment></comment>

174<comment><comment></comment>- [hsWidget](https:<comment>//github.com/HelpfulScripts/hsWidget)</comment></comment>

175<comment><comment></comment>- [webpack](https:<comment>//webpack.js.org/)</comment></comment>

176<comment><comment></comment></comment>

177<comment>## Structural Code Overview</comment>

178<comment>The main entry point for the web-app is index.ts, which initiates loading the docsets </comment>

179<comment>and sets up a mithril {@link hsDocs:Router router} </comment>

180<comment></comment>

181<comment>*/</comment>

182

183<comment>/** */</comment>