documentary
Advanced tools
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
101027
962
624