New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
documentary
Advanced tools
documentary - npm Package Compare versions
Comparing version 1.7.0 to 1.8.0
@@ -15,3 +15,3 @@ "use strict"; | ||
| const getLink = title => { | ||
| const l = title.replace(/<br\/>/g, '').replace(/ /g, '').replace(/[^\w-\d ]/g, '').toLowerCase().replace(/[, ]/g, '-'); | ||
| const l = title.replace(/<\/?code>/g, '').replace(/<\/?strong>/g, '').replace(/<br\/>/g, '').replace(/ /g, '').replace(/[^\w-\d ]/g, '').toLowerCase().replace(/[, ]/g, '-'); | ||
| return l; | ||
@@ -18,0 +18,0 @@ }; |
@@ -28,2 +28,4 @@ "use strict"; | ||
| var _type = _interopRequireDefault(require("./rules/type")); | ||
| function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } | ||
@@ -56,3 +58,3 @@ | ||
| }); | ||
| const s = new _restream.Replaceable([cutInnerCode, cutTable, cutMethodTitle, cutCode, _rules.commentRule, _rules.badgeRule, _tree.default, _example.default, _fork.default, tocRule, _gif.default, insertTable, _table.default, { | ||
| const s = new _restream.Replaceable([cutInnerCode, cutTable, cutMethodTitle, cutCode, _rules.commentRule, _rules.badgeRule, _tree.default, _example.default, _fork.default, tocRule, _gif.default, _type.default, insertTable, _table.default, { | ||
| re: _rules.linkTitleRe, | ||
@@ -59,0 +61,0 @@ |
@@ -24,2 +24,4 @@ "use strict"; | ||
| var _type = _interopRequireDefault(require("./rules/type")); | ||
| function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } | ||
@@ -60,3 +62,3 @@ | ||
| }, cutTable, cutMethodTitle, cutCode, _rules.commentRule, insertMethodTitle, insertTable, insertLinkTitle, insertInnerCode, insertTitle]); | ||
| }, cutTable, cutMethodTitle, cutCode, _rules.commentRule, _type.default, insertMethodTitle, insertTable, insertLinkTitle, insertInnerCode, insertTitle]); | ||
| const c = new _catchment.default({ | ||
@@ -116,8 +118,10 @@ rs | ||
| this.level = length; | ||
| if (this.skipLevelOne && this.level == 1) continue; | ||
| const bb = res.slice(4, 6).filter(a => a).join(' ').trim(); | ||
| const json = res[7] || '[]'; | ||
| const args = JSON.parse(json); | ||
| const s = args.map(([name, type]) => { | ||
| if (typeof type == 'string') return `${name}: ${type}`; | ||
| return `${name}: object`; | ||
| const s = args.map(([name, type, shortType]) => { | ||
| let tt; | ||
| if (shortType) tt = shortType;else if (typeof type == 'string') tt = type;else tt = 'object'; | ||
| return `${name}: ${tt}`; | ||
| }); | ||
@@ -136,7 +140,8 @@ const fullTitle = (0, _methodTitle.replaceTitle)(...res.slice(3)).replace(/^#+ +/, ''); | ||
| if (!level) level = this.level; | ||
| level = this.skipLevelOne ? level - 1 : level; | ||
| if (level == 2) { | ||
| if (level == 1) { | ||
| s = `- ${heading}`; | ||
| } else { | ||
| const p = ' '.repeat(Math.max(level - 2, 0)); | ||
| const p = ' '.repeat(Math.max(level - 1, 0)); | ||
| s = `${p}* ${heading}`; | ||
@@ -143,0 +148,0 @@ } |
@@ -0,1 +1,9 @@ | ||
| ## 26 June 2018 | ||
| ### 1.8.0 | ||
| - [feat] Document types with `%TYPE%` marker. | ||
| - [feat] Use short argument type for TOC from method titles. | ||
| - [doc] document `skipLevelOne` better, remove VS Code ignoring README note. | ||
| ## 24 June 2018 | ||
@@ -2,0 +10,0 @@ |
| { | ||
| "name": "documentary", | ||
| "version": "1.7.0", | ||
| "version": "1.8.0", | ||
| "description": "A library to manage documentation, such as README, usage, man pages and changelog.", | ||
@@ -19,3 +19,4 @@ "main": "build", | ||
| "example/toc.js": "NODE_DEBUG=doc yarn e example/toc.js", | ||
| "build-src": "b --source-maps --ignore src/bin/register.js", | ||
| "example/toc2.js": "NODE_DEBUG=doc yarn e example/toc2.js", | ||
| "b": "b --source-maps --ignore src/bin/register.js", | ||
| "build": "yarn-s build-src doc" | ||
@@ -22,0 +23,0 @@ }, |
187
README.md
@@ -15,3 +15,2 @@ # documentary | ||
| - [Installation & Usage](#installation--usage) | ||
| * [VS Code Settings](#vs-code-settings) | ||
| - [Features](#features) | ||
@@ -23,3 +22,3 @@ * [TOC Generation](#toc-generation) | ||
| * [Method Title](#method-title) | ||
| * [`async runSoftware(path: string, config: object): string`](#async-runsoftwarepath-stringconfig-view-containeractions-objectstatic-boolean--truerender-function-string) | ||
| * [`async runSoftware(path: string, config: Config): string`](#async-runsoftwarepath-stringconfig-view-containeractions-objectstatic-boolean--truerender-function-string) | ||
| * [`async runSoftware(path: string)`](#async-runsoftwarepath-string-void) | ||
@@ -35,7 +34,10 @@ * [`runSoftware(): string`](#runsoftware-string) | ||
| * [Gif Detail](#gif-detail) | ||
| * [<code>yarn doc</code>](#codeyarn-doccode) | ||
| * [<code>yarn doc</code>](#yarn-doc) | ||
| * [`Type` Definition](#type-definition) | ||
| - [CLI](#cli) | ||
| - [API](#api) | ||
| * [`Toc` Type](#toc-type) | ||
| * [`constructor(config?: object): Toc`](#constructorconfig-skiplevelone-boolean--true-toc) | ||
| * [`Toc` Stream](#toc-stream) | ||
| * [`TocConfig` Type](#tocconfig-type) | ||
| * [<code>skipLevelOne</code>](#skiplevelone) | ||
| * [`constructor(config?: TocConfig): Toc`](#constructorconfig-skiplevelone-boolean--true-toc) | ||
@@ -66,13 +68,2 @@ ## Installation & Usage | ||
| ``` | ||
| ### VS Code Settings | ||
| It might be confusing to have a source and output `README.md` file, therefore to prevent errors, the following snippet can be used to hide the compiled file from VS Code search (update the `.vscode/settings.json` file): | ||
| ```json | ||
| { | ||
| "search.exclude": { | ||
| "**/README.md": true | ||
| } | ||
| } | ||
| ``` | ||
| ## Features | ||
@@ -122,3 +113,3 @@ | ||
| It is possible to generate neat titles useful for API documentation with `documentary`. The method signature should be specified as a `JSON` array, where every member is an argument specified as an array. The first item in the argument array is the argument name, and the second one is type. Type can be either a string, or an object. If it is an object, each value in the object will first contain the property type, and the second one the default value. To mark a property as optional, the `?` symbol can be used at the end. | ||
| It is possible to generate neat titles useful for API documentation with `documentary`. The method signature should be specified as a `JSON` array, where every member is an argument specified as an array. The first item in the argument array is the argument name, and the second one is type. Type can be either a string, or an object. If it is an object, each value in the object will be an array and first contain the property type, secondly - the default value. To mark a property as optional, the `?` symbol can be used at the end. The third item is the short name for the table of contents (so that a complex object can be referenced to its type). | ||
@@ -138,3 +129,3 @@ #### `async runSoftware(`<br/> `path: string,`<br/> `config: {`<br/> `View: Container,`<br/> `actions: object,`<br/> `static?: boolean = true,`<br/> `render?: function,`<br/> `},`<br/>`): string` | ||
| "render?": ["function"] | ||
| }] | ||
| }, "Config"] | ||
| ] | ||
@@ -187,2 +178,3 @@ ``` | ||
| │ ├── 8-gif.md | ||
| │ ├── 9-type.md | ||
| │ └── index.md | ||
@@ -264,3 +256,3 @@ ├── 3-cli.md | ||
| <details> | ||
| <summary>Click to View: <a name="codeyarn-doccode"><code>yarn doc</code></a></summary> | ||
| <summary>Click to View: <a name="yarn-doc"><code>yarn doc</code></a></summary> | ||
| <table> | ||
@@ -286,2 +278,109 @@ <tr><td> | ||
| ``` | ||
| ### `Type` Definition | ||
| Often, it is required to document a type of an object, which methods can use. To display the information about type's properties in a table, the `TYPE` macro can be used. It allows to show all possible properties that an object can contain, show which ones are required, give examples and link them in the table of contents (disabled by default). | ||
| Its signature is as follows: | ||
| ```xml | ||
| %TYPE addToToc(true|false) | ||
| <p name="propertyName" type="propertyType" required> | ||
| <d>Property Description.</d> | ||
| <d>Property Example.</d> | ||
| </p> | ||
| % | ||
| ``` | ||
| For example, | ||
| ````xml | ||
| %TYPE | ||
| <p name="text" type="string" required> | ||
| <d>Display text. Required.</d> | ||
| <e> | ||
| ```js | ||
| const q = { | ||
| text: 'What is your name', | ||
| } | ||
| ``` | ||
| </e> | ||
| </p> | ||
| <p name="validation" type="(async) function"> | ||
| <d>A function which needs to throw an error if validation does not pass.</d> | ||
| <e> | ||
| ```js | ||
| const q = { | ||
| text: 'What is your name', | ||
| validate(v) { | ||
| if (!v.length) throw new Error('Name is required.') | ||
| }, | ||
| } | ||
| ``` | ||
| </e> | ||
| </p> | ||
| % | ||
| ```` | ||
| will display the following table: | ||
| <table> | ||
| <tr> | ||
| <th>Property</th> | ||
| <th>Type</th> | ||
| <th>Description</th> | ||
| <th>Example</th> | ||
| </tr> | ||
| <tr> | ||
| <td><strong><code>text</code></strong></td> | ||
| <td><em>string</em></td> | ||
| <td>Display text. Required.</td> | ||
| <td> | ||
| ```js | ||
| const q = { | ||
| text: 'What is your name', | ||
| } | ||
| ``` | ||
| </td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>validation</code></td> | ||
| <td><em>(async) function</em></td> | ||
| <td>A function which needs to throw an error if validation does not pass.</td> | ||
| <td> | ||
| ```js | ||
| const q = { | ||
| text: 'What is your name', | ||
| validate(v) { | ||
| if (!v.length) throw new Error('Name is required.') | ||
| }, | ||
| } | ||
| ``` | ||
| </td> | ||
| </tr> | ||
| </table> | ||
| When required to use the markdown syntax in tables (such as `__`, links, _etc_), an extra space should be left after the `d` or `e` tags like so: | ||
| ``` | ||
| %TYPE true | ||
| <p name="skipLevelOne" type="boolean"> | ||
| <d> | ||
| Start the table of contents from level 2, i.e., excluding the `#` title.</d> | ||
| </p> | ||
| % | ||
| ``` | ||
| Otherwise, the content will not be processed by `GitHub`. However, it will add an extra margin to the content of the cell as it will be transformed into a paragraph. | ||
| ## CLI | ||
@@ -312,6 +411,54 @@ | ||
| The programmatic use of the `documentary` is intended for developers who want to use this software in their projects. | ||
| ### `Toc` Type | ||
| ### `Toc` Stream | ||
| `Toc` is a transform stream which can generate a table of contents for incoming markdown data. For every title that the transform sees, it will push the appropriate level of the table of contents. | ||
| ### `TocConfig` Type | ||
| When creating a new `Toc` instance, it will accept the following configuration object. | ||
| <table> | ||
| <tr> | ||
| <th>Property</th> | ||
| <th>Type</th> | ||
| <th>Description</th> | ||
| <th>Example</th> | ||
| </tr> | ||
| <tr> | ||
| <td><a name="skiplevelone"><code>skipLevelOne</code></a></td> | ||
| <td><em>boolean</em></td> | ||
| <td>Start the table of contents from level 2, i.e., excluding the <code>#</code> title.</td> | ||
| <td>For example, the following code: | ||
| ```md | ||
| # Hello World | ||
| ## Table Of Contents | ||
| ## Introduction | ||
| ``` | ||
| will be compiled to | ||
| ```md | ||
| - [Table Of Contents](#table-of-contents) | ||
| - [Introduction](#introduction) | ||
| ``` | ||
| when `skipLevelOne` is not set (by default), and to | ||
| ```md | ||
| - [Hello World](#hello-world) | ||
| * [Table Of Contents](#table-of-contents) | ||
| * [Introduction](#introduction) | ||
| ``` | ||
| when `skipLevelOne` is set to `false`. | ||
| </td> | ||
| </tr> | ||
| </table> | ||
| ### `constructor(`<br/> `config?: {`<br/> `skipLevelOne?: boolean = true,`<br/> `},`<br/>`): Toc` | ||
@@ -318,0 +465,0 @@ |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
No alert changes
Improved metrics
- Total package byte prevSize
- increased by18.41%
91527
- Number of package files
- increased by6.25%
34
- Lines of code
- increased by19.62%
890
- Number of lines in readme file
- increased by42.61%
492
No dependency changes