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.9.0 to 1.10.0
@@ -10,10 +10,4 @@ "use strict"; | ||
| const LOG = (0, _util.debuglog)('doc'); // `%TYPE Name | ||
| // <p> | ||
| // </p> | ||
| // <p> | ||
| // </p> | ||
| // %` | ||
| const typeRe = /^%TYPE( .+)?\n([\s\S]+)\n%$/mg; | ||
| const LOG = (0, _util.debuglog)('doc'); | ||
| const typeRe = /^%TYPE( .+)?\n([\s\S]+?)\n%$/mg; | ||
| exports.typeRe = typeRe; | ||
@@ -91,3 +85,26 @@ | ||
| const getDescAndExample = (description, example, isExampleRow, hasExamples) => { | ||
| const span2 = hasExamples ? ' colspan="2"' : ''; | ||
| if (!example) { | ||
| return `<td${span2}>${description}</td>`; | ||
| } | ||
| if (isExampleRow) { | ||
| return `<td${span2}>${description}</td> | ||
| </tr> | ||
| <tr></tr> | ||
| <tr> | ||
| <td colspan="${hasExamples ? 4 : 3}">${example}</td>`; | ||
| } | ||
| return `<td>${description}</td> | ||
| <td>${example}</td>`; | ||
| }; | ||
| const makeTable = (properties, tocTitles) => { | ||
| const hasExamples = properties.some(({ | ||
| example, | ||
| isExampleRow | ||
| }) => example && !isExampleRow); | ||
| const rows = properties.map(({ | ||
@@ -98,3 +115,4 @@ name, | ||
| description = '', | ||
| example = '' | ||
| example = '', | ||
| isExampleRow | ||
| }) => { | ||
@@ -105,8 +123,7 @@ const t = `<code>${name}</code>`; | ||
| const e = example.startsWith('```') ? `\n\n${example}` : example; | ||
| return ` <tr> | ||
| <td>${nn}</td> | ||
| <td>${tag('em', type)}</td> | ||
| <td>${description}</td> | ||
| <td>${e}</td> | ||
| </tr>`; | ||
| return ` <tr> | ||
| <td>${nn}</td> | ||
| <td>${tag('em', type)}</td> | ||
| ${getDescAndExample(description, e, isExampleRow, hasExamples)} | ||
| </tr>`; | ||
| }); | ||
@@ -118,8 +135,7 @@ return `<table> | ||
| <th>Type</th> | ||
| <th>Description</th> | ||
| <th>Example</th> | ||
| <th>Description</th>${hasExamples ? '\n <th>Example</th>' : ''} | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| ${rows.join('\n')} | ||
| ${rows.join('\n')} | ||
| </tbody> | ||
@@ -143,3 +159,6 @@ </table> | ||
| const [{ | ||
| content: example | ||
| content: example, | ||
| props: { | ||
| row: isExampleRow = false | ||
| } = {} | ||
| } = {}] = extractTag('e', content); | ||
@@ -149,2 +168,3 @@ return { | ||
| example, | ||
| isExampleRow, | ||
| ...props | ||
@@ -151,0 +171,0 @@ }; |
@@ -0,1 +1,7 @@ | ||
| ## 18 July 2018 | ||
| ### 1.10.0 | ||
| - [feature] Dedicated example row in `Type` definition, skip `Examples` header when no non-row examples are given, non-greedy type regex. | ||
| ## 17 July 2018 | ||
@@ -2,0 +8,0 @@ |
| { | ||
| "name": "documentary", | ||
| "version": "1.9.0", | ||
| "version": "1.10.0", | ||
| "description": "A library to manage documentation, such as README, usage, man pages and changelog.", | ||
@@ -5,0 +5,0 @@ "main": "build", |
163
README.md
@@ -34,2 +34,3 @@ # documentary | ||
| * [`Type` Definition](#type-definition) | ||
| * [Dedicated Example Row](#dedicated-example-row) | ||
| - [CLI](#cli) | ||
@@ -335,7 +336,7 @@ * [Output Location](#output-location) | ||
| <tbody> | ||
| <tr> | ||
| <td><strong><code>text</code></strong></td> | ||
| <td><em>string</em></td> | ||
| <td>Display text. Required.</td> | ||
| <td> | ||
| <tr> | ||
| <td><strong><code>text</code></strong></td> | ||
| <td><em>string</em></td> | ||
| <td>Display text. Required.</td> | ||
| <td> | ||
@@ -348,8 +349,8 @@ ```js | ||
| </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> | ||
| </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> | ||
@@ -365,3 +366,3 @@ ```js | ||
| </td> | ||
| </tr> | ||
| </tr> | ||
| </tbody> | ||
@@ -384,2 +385,128 @@ </table> | ||
| 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. | ||
| #### Dedicated Example Row | ||
| Because examples occupy a lot of space which causes table squeezing on GitHub and scrolling on NPM, `documentary` allows to dedicate a special row to an example. It can be achieved by adding a `row` attribute to the `e` element, like so: | ||
| ````xml | ||
| %TYPE | ||
| <p name="headers" type="object"> | ||
| <d>Incoming headers returned by the server.</d> | ||
| <e row> | ||
| ```json | ||
| { | ||
| "server": "GitHub.com", | ||
| "content-type": "application/json", | ||
| "content-length": "2", | ||
| "connection": "close", | ||
| "status": "200 OK" | ||
| } | ||
| ``` | ||
| </e> | ||
| </p> | ||
| % | ||
| ```` | ||
| In addition, any properties which do not contain examples will not have an example column at all. | ||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Property</th> | ||
| <th>Type</th> | ||
| <th>Description</th> | ||
| <th>Example</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><code>body</code></td> | ||
| <td><em>string|object|Buffer</em></td> | ||
| <td colspan="2">The return from the server.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>headers</code></td> | ||
| <td><em>object</em></td> | ||
| <td colspan="2">Incoming headers returned by the server.</td> | ||
| </tr> | ||
| <tr></tr> | ||
| <tr> | ||
| <td colspan="4"> | ||
| ```json | ||
| { | ||
| "server": "GitHub.com", | ||
| "content-type": "application/json", | ||
| "content-length": "2", | ||
| "connection": "close", | ||
| "status": "200 OK" | ||
| } | ||
| ``` | ||
| </td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>statusCode</code></td> | ||
| <td><em>number</em></td> | ||
| <td>The status code returned by the server.</td> | ||
| <td><code>200</code></td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
| Finally, when no examples which are not rows are given, there will be no `Example` heading. | ||
| ````xml | ||
| %TYPE | ||
| <p name="data" type="object"> | ||
| <d>Optional data to send to the server with the request.</d> | ||
| <e row> | ||
| ```js | ||
| { | ||
| name: 'test', | ||
| } | ||
| ``` | ||
| </e> | ||
| </p> | ||
| <p name="method" type="string"> | ||
| <d>What HTTP method to use to send data (only works when <code>data</code> is set).</d> | ||
| </p> | ||
| % | ||
| ```` | ||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Property</th> | ||
| <th>Type</th> | ||
| <th>Description</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><code>data</code></td> | ||
| <td><em>object</em></td> | ||
| <td>Optional data to send to the server with the request.</td> | ||
| </tr> | ||
| <tr></tr> | ||
| <tr> | ||
| <td colspan="3"> | ||
| ```js | ||
| { | ||
| name: 'test', | ||
| } | ||
| ``` | ||
| </td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>method</code></td> | ||
| <td><em>string</em></td> | ||
| <td>What HTTP method to use to send data (only works when <code>data</code> is set).</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
| ## CLI | ||
@@ -428,7 +555,7 @@ | ||
| <tbody> | ||
| <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: | ||
| <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: | ||
@@ -460,3 +587,3 @@ ```md | ||
| </td> | ||
| </tr> | ||
| </tr> | ||
| </tbody> | ||
@@ -463,0 +590,0 @@ </table> |
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 by4.63%
101027
- Lines of code
- increased by1.8%
962
- Number of lines in readme file
- increased by25.55%
624
No dependency changes