Huge News!Announcing our $40M Series B led by Abstract Ventures.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
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
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