New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More
Socket
Sign inDemoInstall
Socket

documentary

Package Overview
Dependencies
Maintainers
1
Versions
118
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

documentary - npm Package Compare versions

Comparing version 1.20.1 to 1.21.0

build/lib/components.js

17

build/bin/index.js

@@ -5,10 +5,17 @@ #!/usr/bin/env node

const { lstatSync } = require('fs');
let run = require('./run'); if (run && run.__esModule) run = run.default;
let getArgs = require('./get-args'); if (getArgs && getArgs.__esModule) getArgs = getArgs.default;
let generateTypedef = require('./run/generate'); if (generateTypedef && generateTypedef.__esModule) generateTypedef = generateTypedef.default;
let extractTypedef = require('./run/extract'); if (extractTypedef && extractTypedef.__esModule) extractTypedef = extractTypedef.default;
let alamode = require('alamode'); if (alamode && alamode.__esModule) alamode = alamode.default;
const { dirname } = require('path');
const run = require('./run');
const getArgs = require('./get-args');
const generateTypedef = require('./run/generate');
const extractTypedef = require('./run/extract');
const { version } = require('../../package.json');
let catcher = require('./catcher'); if (catcher && catcher.__esModule) catcher = catcher.default;
const catcher = require('./catcher');
const { gitPush } = require('../lib');
const preact = dirname(require.resolve('preact/package.json'))
alamode({
pragma: `const { h } = require("${preact}");`,
})
const LOG = debuglog('doc')

@@ -15,0 +22,0 @@ const DEBUG = /doc/.test(process.env.NODE_DEBUG)

let whichStream = require('which-stream'); if (whichStream && whichStream.__esModule) whichStream = whichStream.default;
const { getToc } = require('../lib/Toc');
let Documentary = require('../lib/Documentary'); if (Documentary && Documentary.__esModule) Documentary = Documentary.default;
const Documentary = require('../lib/Documentary');
const { getStream } = require('../lib');

@@ -5,0 +5,0 @@ const { getTypedefs } = require('../lib/Typedefs');

@@ -6,5 +6,5 @@ const { createReadStream } = require('fs');

let whichStream = require('which-stream'); if (whichStream && whichStream.__esModule) whichStream = whichStream.default;
let catcher = require('../catcher'); if (catcher && catcher.__esModule) catcher = catcher.default;
const catcher = require('../catcher');
const { debuglog } = require('util');
let typedefRe = require('../../lib/typedef/re'); if (typedefRe && typedefRe.__esModule) typedefRe = typedefRe.default;
const typedefRe = require('../../lib/typedef/re');
const { getNameWithDefault } = require('typal');

@@ -11,0 +11,0 @@

const { createReadStream } = require('fs');
const { debuglog } = require('util');
let whichStream = require('which-stream'); if (whichStream && whichStream.__esModule) whichStream = whichStream.default;
let createJsReplaceStream = require('../../lib/js-replace-stream'); if (createJsReplaceStream && createJsReplaceStream.__esModule) createJsReplaceStream = createJsReplaceStream.default;
let catcher = require('../catcher'); if (catcher && catcher.__esModule) catcher = catcher.default;
const createJsReplaceStream = require('../../lib/js-replace-stream');
const catcher = require('../catcher');

@@ -7,0 +7,0 @@ const LOG = debuglog('doc')

@@ -5,19 +5,32 @@ const { Replaceable, makeMarkers, makeCutRule, makePasteRule } = require('restream');

} = require('./rules');
let tableRule = require('./rules/table'); const { tableRe } = tableRule; if (tableRule && tableRule.__esModule) tableRule = tableRule.default;
let methodTitleRule = require('./rules/method-title'); const { methodTitleRe } = methodTitleRule; if (methodTitleRule && methodTitleRule.__esModule) methodTitleRule = methodTitleRule.default;
let treeRule = require('./rules/tree'); if (treeRule && treeRule.__esModule) treeRule = treeRule.default;
let exampleRule = require('./rules/example'); if (exampleRule && exampleRule.__esModule) exampleRule = exampleRule.default;
let forkRule = require('./rules/fork'); if (forkRule && forkRule.__esModule) forkRule = forkRule.default;
const tableRule = require('./rules/table'); const { tableRe } = tableRule;
const methodTitleRule = require('./rules/method-title'); const { methodTitleRe } = methodTitleRule;
const treeRule = require('./rules/tree');
const exampleRule = require('./rules/example');
const forkRule = require('./rules/fork');
const { getLink } = require('.');
let gifRule = require('./rules/gif'); if (gifRule && gifRule.__esModule) gifRule = gifRule.default;
let typeRule = require('./rules/type'); if (typeRule && typeRule.__esModule) typeRule = typeRule.default;
let badgeRule = require('./rules/badge'); if (badgeRule && badgeRule.__esModule) badgeRule = badgeRule.default;
const gifRule = require('./rules/gif');
const typeRule = require('./rules/type');
const badgeRule = require('./rules/badge');
const { typedefMdRe } = require('./rules/typedef-md');
let tableMacroRule = require('./rules/macro'); if (tableMacroRule && tableMacroRule.__esModule) tableMacroRule = tableMacroRule.default;
let sectionBrakeRule = require('./rules/section-break'); if (sectionBrakeRule && sectionBrakeRule.__esModule) sectionBrakeRule = sectionBrakeRule.default;
const tableMacroRule = require('./rules/macro');
const sectionBrakeRule = require('./rules/section-break');
const { debuglog } = require('util');
const { macroRule, useMacroRule } = require('./rules/macros');
const { join, resolve } = require('path');
const { homedir } = require('os');
const loadComponents = require('./components');
const LOG = debuglog('doc')
const getComponents = (path) => {
try {
const transforms = require(path)
const components = loadComponents(transforms)
return components
} catch (err) {
return []
}
}
/**

@@ -32,3 +45,9 @@ * Documentary is a _Replaceable_ stream with transform rules for documentation.

constructor(options = {}) {
const { toc, locations = {}, types: allTypes = [] } = options
const {
toc, locations = {}, types: allTypes = [],
cwd = '.',
} = options
const hm = getComponents(join(homedir(), '.documentary'))
const cm = getComponents(resolve(cwd, '.documentary'))
const components = [...cm, ...hm]
const tocRule = createTocRule(toc)

@@ -81,3 +100,3 @@

sectionBrakeRule,
...components,
insertTable,

@@ -84,0 +103,0 @@ // typedefMdRule, // places a table hence just before table

@@ -5,4 +5,4 @@ const { createReadStream, lstatSync } = require('fs');

let Pedantry = require('pedantry'); if (Pedantry && Pedantry.__esModule) Pedantry = Pedantry.default;
let tableRule = require('./rules/table'); if (tableRule && tableRule.__esModule) tableRule = tableRule.default;
let titleRule = require('./rules/method-title'); if (titleRule && titleRule.__esModule) titleRule = titleRule.default;
const tableRule = require('./rules/table');
const titleRule = require('./rules/method-title');

@@ -9,0 +9,0 @@ const getLink = (title, prefix = '') => {

@@ -1,2 +0,2 @@

let JSDocumentary = require('./JSDocumentary'); if (JSDocumentary && JSDocumentary.__esModule) JSDocumentary = JSDocumentary.default;
const JSDocumentary = require('./JSDocumentary');

@@ -3,0 +3,0 @@ /** @typedef {import('./typedef/Type').default} Type */

const { Replaceable } = require('restream');
let typedefJsRule = require('./rules/typedef-js'); if (typedefJsRule && typedefJsRule.__esModule) typedefJsRule = typedefJsRule.default;
let JSDocRule = require('./typedef/jsdoc'); if (JSDocRule && JSDocRule.__esModule) JSDocRule = JSDocRule.default;
const typedefJsRule = require('./rules/typedef-js');
const JSDocRule = require('./typedef/jsdoc');

@@ -5,0 +5,0 @@ class JSDocumentary extends Replaceable {

@@ -1,2 +0,2 @@

let Documentary = require('./Documentary'); if (Documentary && Documentary.__esModule) Documentary = Documentary.default;
const Documentary = require('./Documentary');

@@ -3,0 +3,0 @@ function createReplaceStream(toc) {

const { fork } = require('spawncommand');
const { codeSurround } = require('..');;
const { codeSurround } = require('..');
// import { debuglog } from 'util'

@@ -4,0 +4,0 @@

@@ -8,4 +8,4 @@ const { Transform } = require('stream');

} = require('./rules');
let tableRule = require('./rules/table'); if (tableRule && tableRule.__esModule) tableRule = tableRule.default;
let tableMacroRule = require('./rules/macro'); if (tableMacroRule && tableMacroRule.__esModule) tableMacroRule = tableMacroRule.default;
const tableRule = require('./rules/table');
const tableMacroRule = require('./rules/macro');
const {

@@ -15,3 +15,3 @@ Replaceable, makeCutRule, makePasteRule, makeMarkers,

const { tableRe } = require('./rules/table');
let typeRule = require('./rules/type'); if (typeRule && typeRule.__esModule) typeRule = typeRule.default;
const typeRule = require('./rules/type');
const { typedefMdRe } = require('./rules/typedef-md');

@@ -18,0 +18,0 @@ const { macroRule, useMacroRule } = require('./rules/macros');;

@@ -0,1 +1,7 @@

## 25 January 2018
### 1.21.0
- [feature] Reusable JSX components.
## 25 September 2018

@@ -2,0 +8,0 @@

{
"name": "documentary",
"version": "1.20.1",
"version": "1.21.0",
"description": "A Documentation Pre-processor To Generate The Table Of Contents, Embed Examples With Their Output, Make Markdown Tables, Maintain Typedefs For JavaScript And README, Watch Changes To Push, Use Macros And Prettify API Titles.",

@@ -28,3 +28,4 @@ "main": "build",

"bin": {
"doc": "build/bin/index.js"
"doc": "build/bin/index.js",
"doc-dev": "src/bin/alamode.js"
},

@@ -82,19 +83,21 @@ "man": "man/doc.1",

"devDependencies": {
"alamode": "1.5.1",
"eslint-config-artdeco": "1.0.1",
"snapshot-context": "2.0.4",
"temp-context": "1.1.0",
"temp-context": "2.1.0",
"yarn-s": "1.1.0",
"zoroaster": "3.5.1"
"zoroaster": "3.6.6"
},
"dependencies": {
"@wrote/clone": "1.0.1",
"@wrote/ensure-path": "1.0.3",
"argufy": "1.2.1",
"catchment": "3.1.1",
"erte": "1.1.4",
"@wrote/clone": "1.1.0",
"@wrote/ensure-path": "1.0.5",
"alamode": "1.7.0",
"argufy": "1.3.2",
"catchment": "3.2.2",
"erte": "1.1.6",
"mismatch": "1.0.3",
"pedantry": "2.2.0",
"restream": "3.2.1",
"rexml": "1.1.0",
"preact": "8.4.2",
"preact-render-to-string": "4.1.0",
"restream": "3.5.0",
"rexml": "1.2.0",
"spawncommand": "2.1.0",

@@ -101,0 +104,0 @@ "typal": "1.2.0",

@@ -25,2 +25,3 @@ Documentary

| *[Forks](#embedding-output)* | Makes it possible to run an example and embed its `stdout` and `stderr` output directly into documentation. | 1. Enhances productivity by eliminating the need to copy and paste the output by hand.<br/>2. Makes sure the output is always up-to-date with the documented one.<br/>3. Will make it visible if a change to the code base lead to a different output (implicit regression testing).<br/>4. Ensures that examples are actually working.<br/>5. Can print usage of CLI tools by forking them with `-h` command. |
| *[JSX Components](#jsx-components)* | Performs the compilation of custom-defined JSX components into markdown code. | 1. Lets to define custom components and reuse them across documentation where needed. <br/>2. Provides a modern syntax to combine markdown and JavaScript. |
| *[Tables](#simple-tables)* | Compiles tables from arrays without having to write html or markdown. | 1. Removes the need to manually build tables either by hand, online or using other tools.<br/>2. Provides table macros to reduce repetitive information and substitute only the core data into templates. |

@@ -54,2 +55,3 @@ | *[Macros](#macros)* | Reuses a defined template to place the data into placeholders. | 1. Removes the need to copy-paste patterns to different places and change data manually.<br/>2. Maintains an up-to-date version of the template without having to change it everywhere.<br/>3. Reduces the cluttering of the source documentation by noise and helps to focus on important information. |

* [`runSoftware()`](#runsoftware-void)
- [**JSX Components**](#jsx-components)
- [**Comments Stripping**](#comments-stripping)

@@ -67,5 +69,5 @@ - [**Macros**](#macros)

* [README placement](#readme-placement)
* [`SetHeaders`](#setheaders)
* [`RightsConfig`](#rightsconfig)
* [`StaticConfig`](#staticconfig)
* [`SetHeaders`](#type-setheaders)
* [`RightsConfig`](#type-rightsconfig)
* [`StaticConfig`](#type-staticconfig)
* [Advanced Usage](#advanced-usage)

@@ -95,3 +97,2 @@ * [Spread `@param`](#spread-param)

* [Editor Documentation](#editor-documentation)
- [TODO](#todo)
- [Copyright](#copyright)

@@ -554,2 +555,59 @@

## **JSX Components**
_Documentary_ lets users define their custom components in the `.documentary` folder both in the project directory and the user's home directory. The components are written using JSX syntax and exported as named functions from `jsx` files. The properties the component receives are extracted from the markdown syntax and passed to the hyperscript constructor (from `preact`).
For example, the user can define their own component in the following way:
```jsx
/**
* Display the sponsor information.
*/
export const Sponsor = ({
name, link, image, children,
}) => {
return <table>
<tr/>
<tr>
<td align="center">
<a href={link}>
<img src={image} alt={name}/>
</a><br/>
Sponsored by <a href={link}>{name}</a>.
</td>
</tr>
{children && <tr><td>{children}</td></tr>}
</table>
}
```
And then invoke it in the documentation:
```html
<Sponsor name="Tech Nation Visa Sucks"
link="https://www.technation.sucks"
image="sponsor.gif">
Get In Touch To Support Documentary
</Sponsor>
```
The result will be rendered HTML:
<table>
<tr></tr>
<tr>
<td align="center">
<a href="https://www.technation.sucks">
<img src="https://raw.githubusercontent.com/artdecoweb/www.technation.sucks/master/anim.gif" alt="Tech Nation Visa Sucks" />
</a><br />
Sponsored by <a href="https://www.technation.sucks">Tech Nation Visa Sucks</a>.
</td>
</tr>
<tr><td>
Get In Touch To Support Documentary
</td></tr>
</table>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/9.svg?sanitize=true"></a></p>
## **Comments Stripping**

@@ -559,3 +617,3 @@

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/9.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/10.svg?sanitize=true"></a></p>

@@ -617,3 +675,3 @@ ## **Macros**

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/10.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/11.svg?sanitize=true"></a></p>

@@ -645,2 +703,3 @@ ## **File Splitting**

│   ├── 3-method-title.md
│   ├── 3.5-jsx-components.md
│   ├── 4-comment-stripping.md

@@ -662,3 +721,3 @@ │   ├── 4-macros.md

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/11.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/12.svg?sanitize=true"></a></p>

@@ -675,3 +734,3 @@ ## **Replacement Rules**

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/12.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/13.svg?sanitize=true"></a></p>

@@ -712,3 +771,3 @@ ## **Gif Detail**

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/13.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/14.svg?sanitize=true"></a></p>

@@ -947,3 +1006,3 @@ ## **`Type` Definition**

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/14.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/15.svg?sanitize=true"></a></p>

@@ -1128,18 +1187,18 @@ ## **`@typedef` Organisation**

[`import('http').ServerResponse`](https://nodejs.org/api/http.html#http_class_http_serverresponse) __<a name="serverresponse">`ServerResponse`</a>__
[`import('http').ServerResponse`](https://nodejs.org/api/http.html#http_class_http_serverresponse) __<a name="type-serverresponse">`ServerResponse`</a>__
`(res: ServerResponse) => any` __<a name="setheaders">`SetHeaders`</a>__: Function to set custom headers on response.
`(res: ServerResponse) => any` __<a name="type-setheaders">`SetHeaders`</a>__: Function to set custom headers on response.
`{ location: string, rights: number }[]` __<a name="rightsconfig">`RightsConfig`</a>__: Configuration of read and write access rights.
`{ location: string, rights: number }[]` __<a name="type-rightsconfig">`RightsConfig`</a>__: Configuration of read and write access rights.
__<a name="staticconfig">`StaticConfig`</a>__: Options to setup `koa-static`.
__<a name="type-staticconfig">`StaticConfig`</a>__: Options to setup `koa-static`.
| Name | Type | Description | Default |
| ------------- | ----------------------------------------------- | --------------------------------------------------------------- | ------------ |
| __root*__ | _string_ | Root directory string. | - |
| maxage | _number_ | Browser cache max-age in milliseconds. | `0` |
| hidden | _boolean_ | Allow transfer of hidden files. | `false` |
| index | _string_ | Default file name. | `index.html` |
| setHeaders | _[SetHeaders](#setheaders)_ | Function to set custom headers on response. | - |
| rightsPromise | _Promise.&lt;[RightsConfig](#rightsconfig)&gt;_ | The promise which will be resolved with access rights to files. | - |
| Name | Type | Description | Default |
| ------------- | ---------------------------------------------------- | --------------------------------------------------------------- | ------------ |
| __root*__ | _string_ | Root directory string. | - |
| maxage | _number_ | Browser cache max-age in milliseconds. | `0` |
| hidden | _boolean_ | Allow transfer of hidden files. | `false` |
| index | _string_ | Default file name. | `index.html` |
| setHeaders | _[SetHeaders](#type-setheaders)_ | Function to set custom headers on response. | - |
| rightsPromise | _Promise.&lt;[RightsConfig](#type-rightsconfig)&gt;_ | The promise which will be resolved with access rights to files. | - |

@@ -1402,3 +1461,3 @@ _Documentary_ wil scan each source file of the documentation first to build a map of all types. Whenever a property appears to be of a known type, it will be automatically linked to the location where it was defined. It is also true for properties described as generic types, such as `Promise.<Type>`. This makes it possible to define all types in one place, and then reference them in the API documentation.

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/15.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/16.svg?sanitize=true"></a></p>

@@ -1434,3 +1493,3 @@ ## CLI

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/16.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/17.svg?sanitize=true"></a></p>

@@ -1527,3 +1586,3 @@ ## API

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/17.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/18.svg?sanitize=true"></a></p>

@@ -1546,3 +1605,3 @@ #PRO

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/18.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/19.svg?sanitize=true"></a></p>

@@ -1556,16 +1615,2 @@ ## Glossary

## TODO
- [ ] Test using `zoroaster`'s masks.
- [ ] Gather all types across the whole documentation first to be able to independently link them even if they are in separate files.
- [x] Replace the source in example with a `require` call in addition to `import` statement.
- [ ] Implement caching.
- [ ] Trigger compilation whenever an embedded example changes.
- [ ] Purge image cache from CLI (e.g., `curl -X https://github.com/artdecocode/documentary/raw/${BRANCH}${PATH}`)
- [ ] Implement JS-based `tree`.
- [ ] Implement a proper logging system without `NODE_DEBUG`.
- [ ] Add more section breaks.
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/-2.svg?sanitize=true"></a></p>
## Copyright

@@ -1575,6 +1620,21 @@

(c) [Art Deco][1] 2018
<table>
<tr>
<th>
<a href="https://artd.eco">
<img src="https://raw.githubusercontent.com/wrote/wrote/master/images/artdeco.png" alt="Art Deco" />
</a>
</th>
<th>© <a href="https://artd.eco">Art Deco</a> 2019</th>
<th>
<a href="https://www.technation.sucks" title="Tech Nation Visa">
<img src="https://raw.githubusercontent.com/artdecoweb/www.technation.sucks/master/anim.gif" alt="Tech Nation Visa" />
</a>
</th>
<th>
<a href="https://www.technation.sucks">Tech Nation Visa Sucks</a>
</th>
</tr>
</table>
[1]: https://artdeco.bz
<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/-1.svg?sanitize=true"></a></p>

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

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc