documentary - npm Package Compare versions

Comparing version 1.28.0 to 1.28.1

build/bin/doc.js

 #!/usr/bin/env node
-const { _source, _output, _toc, _watch, _push, _version, _extract, _h1, _reverse, _generate, _noCache, _namespace, _help, argsConfig, _wiki, _types } = require('./get-args');
+const { _source, _output, _toc, _watch, _push, _version, _extract, _h1, _reverse, _generate, _noCache, _namespace, _help, argsConfig, _wiki, _types, _focus } = require('./get-args');
 const { watch } = require('fs');
@@ -61,3 +61,3 @@ const { debuglog } = require('util');
     reverse: _reverse, noCache: _noCache, rootNamespace: _namespace,
-    wiki: _wiki, types: _types,
+    wiki: _wiki, types: _types, focus: _focus,
   }
@@ -64,0 +64,0 @@ let files

build/bin/get-args.js

@@ -14,6 +14,9 @@ let argufy = require('argufy'); if (argufy && argufy.__esModule) argufy = argufy.default;
   'wiki': {
-    description: 'Generate documentation in Wiki mode.',
-    boolean: true,
+    description: 'Generate documentation in Wiki mode. The value of the argument must be the location of wiki, e.g., `../documentary.wiki`. The `--output` option in this case has no effect.',
     short: 'W',
   },
+  'focus': {
+    description: 'When generating _Wiki_, this is a list of comma-separated values used to specify which pages to process in current compilation, e.g., `Address` or `Address,DNS`.',
+    short: 'f',
+  },
   'toc': {
@@ -91,7 +94,12 @@ description: 'Just print the table of contents.',
 /**
- * Generate documentation in Wiki mode.
+ * Generate documentation in Wiki mode. The value of the argument must be the location of wiki, e.g., `../documentary.wiki`. The `--output` option in this case has no effect.
  */
-const _wiki = /** @type {boolean} */ (args['wiki'])
+const _wiki = /** @type {string} */ (args['wiki'])
 
 /**
+ * When generating _Wiki_, this is a list of comma-separated values used to specify which pages to process in current compilation, e.g., `Address` or `Address,DNS`.
+ */
+const _focus = /** @type {string} */ (args['focus'])
+
+/**
  * Just print the table of contents.
@@ -172,2 +180,3 @@ */
 module.exports._wiki = _wiki
+module.exports._focus = _focus
 module.exports._toc = _toc
@@ -174,0 +183,0 @@ module.exports._types = _types

build/bin/run.js

@@ -13,4 +13,3 @@ let whichStream = require('which-stream'); if (whichStream && whichStream.__esModule) whichStream = whichStream.default;
  * Run the documentary and save the results.
- * @param {RunOptions} options Options for the run command.
- * @param {string} options.source The path to the source directory or file.
+ * @param {Object} options Options for the run command.
  * @param {string} [options.output="-"] The path where to save the output. When `-` is passed, prints to `stdout`. Default `-`.
@@ -20,2 +19,3 @@ * @param {boolean} [options.reverse=false] Read files in directories in reverse order, such that `30.md` comes before `1.md`. Useful for blogs. Default `false`.
  * @param {boolean} [options.h1=false] Include `H1` headers in the table of contents. Default `false`.
+ * @param {string} [options.focus] Which pages to process for wiki.
  */
@@ -26,4 +26,6 @@ async function run(options) {
   } = options
-  let { types: typesLocations } = options
 
+  let { types: typesLocations, focus } = options
+  if (focus) focus = focus.split(',')
+
   const stream = getStream(source, reverse, true)
@@ -42,8 +44,14 @@
     if (type != 'Directory') throw new Error('Please point to the wiki directory.')
-    const entries = Object.keys(content).filter((key) => {
+    const keys = Object.keys(content).filter((key) => {
+      const val = content[key]
+      if (focus) {
+        return focus.includes(key)
+      }
+      if (val.type == 'Directory' && !key.startsWith('_')) return true
       return /\.(md|html)$/.test(key)
     })
-    const wo = output || '.'
-    const docs = await Promise.all(entries.map(async (s) => {
-      const o = join(wo, s)
+    const docs = await Promise.all(keys.map(async (s) => {
+      const val = content[s]
+      let o = join(wiki, s)
+      if (val.type == 'Directory') o += '.md'
       const so = join(source, s)
@@ -61,3 +69,3 @@ const doc = await runPage({
     assets = [...assets, docs.map(d => d.assets)]
-    console.log('Saved %s wiki page%s to %s', docs.length, docs.length > 1 ? 's' : '', wo)
+    console.log('Saved %s wiki page%s to %s', docs.length, docs.length > 1 ? 's' : '', wiki)
   } else {
@@ -82,3 +90,3 @@ const doc = await runPage({ source, reverse, locations, types, noCache, h1, justToc, output })
   const doc = new Documentary({
-    locations, types, noCache, objectMode: true, wiki,
+    locations, types, noCache, objectMode: true, wiki, output,
   })
@@ -85,0 +93,0 @@ stream.pipe(doc)

build/components/Argufy.js

@@ -45,3 +45,3 @@ const { h } = require('preact');
   const hasShort = args.some(({ short }) => short)
-  const trs = args.map(({ command, description, name, short, toc, def }, i) => {
+  const trs = args.reduce((acc, { command, description, name, short, toc, def }, i) => {
     const n = command ? name : `--${name}`
@@ -51,14 +51,25 @@ const nn = toc ? `[${n}](t)` : n
     const d = Md2Html({ children: [description], documentary })
-    return (h('tr',{'key':i},
-      h('td',{},nn),
+
+    const r = (h('tr',{'key':i},'\n   ',
+      h('td',{},nn),'\n   ',
       hasShort && h('td',{},short ? `-${short}` : ''),
-      h('td',{'dangerouslySetInnerHTML':{ __html: d }}),
+      hasShort && '\n   ',
+      h('td',{'dangerouslySetInnerHTML':{ __html: d }}),'\n  ',
     ))
-  })
-  return (h('table',{},
-    h('tr',{},
-      h('th',{},`Argument`),
-       hasShort && h('th',{},`Short`),
-      h('th',{},`Description`),
-    ),
+
+    acc.push('  ')
+    acc.push(r)
+    acc.push('\n')
+    return acc
+  }, [])
+  documentary.setPretty(false)
+  return (h('table',{},'\n ',
+    h('thead',{},'\n  ',
+      h('tr',{},'\n   ',
+        h('th',{},`Argument`),` `,'\n   ',
+         hasShort && h('th',{},`Short`),
+         hasShort && '\n   ',
+        h('th',{},`Description`),'\n  ',
+      ),'\n ',
+    ),'\n',
     trs,
@@ -65,0 +76,0 @@ ))

build/components/Argufy.jsx

@@ -44,3 +44,3 @@ const read = require('@wrote/read');
   const hasShort = args.some(({ short }) => short)
-  const trs = args.map(({ command, description, name, short, toc, def }, i) => {
+  const trs = args.reduce((acc, { command, description, name, short, toc, def }, i) => {
     const n = command ? name : `--${name}`
@@ -50,14 +50,25 @@ const nn = toc ? `[${n}](t)` : n
     const d = Md2Html({ children: [description], documentary })
-    return (<tr key={i}>
-      <td>{nn}</td>
+
+    const r = (<tr key={i}>{'\n   '}
+      <td>{nn}</td>{'\n   '}
       {hasShort && <td>{short ? `-${short}` : ''}</td>}
-      <td dangerouslySetInnerHTML={{ __html: d }}></td>
+      {hasShort && '\n   '}
+      <td dangerouslySetInnerHTML={{ __html: d }}/>{'\n  '}
     </tr>)
-  })
-  return (<table>
-    <tr>
-      <th>Argument</th>
-      { hasShort && <th>Short</th>}
-      <th>Description</th>
-    </tr>
+
+    acc.push('  ')
+    acc.push(r)
+    acc.push('\n')
+    return acc
+  }, [])
+  documentary.setPretty(false)
+  return (<table>{'\n '}
+    <thead>{'\n  '}
+      <tr>{'\n   '}
+        <th>Argument</th> {'\n   '}
+        { hasShort && <th>Short</th>}
+        { hasShort && '\n   '}
+        <th>Description</th>{'\n  '}
+      </tr>{'\n '}
+    </thead>{'\n'}
     {trs}
@@ -64,0 +75,0 @@ </table>)

build/lib/Documentary.js

 const { Replaceable, makeMarkers, makeCutRule, makePasteRule } = require('restream');
 const { debuglog, isBuffer } = require('util');
-const { join, resolve } = require('path');
+const { join, resolve, basename } = require('path');
 const { homedir } = require('os');
@@ -57,3 +57,3 @@ let write = require('@wrote/write'); if (write && write.__esModule) write = write.default;
       cwd = '.', cacheLocation = join(cwd, '.documentary/cache'), noCache,
-      disableDtoc, objectMode = true, wiki,
+      disableDtoc, objectMode = true, wiki, output,
     } = options
@@ -198,2 +198,8 @@
     this.assets = []
+    /**
+     * The args passed to the program.
+     */
+    this._args = {
+      output, wiki,
+    }
   }
@@ -279,2 +285,3 @@ /**
     } else if (typeof chunk == 'object') {
+      if (basename(chunk.file) == '.DS_Store') return next()
       chunk.file != 'separator' && LOG(b(chunk.file, 'cyan'))
@@ -281,0 +288,0 @@ this.currentFile = chunk.file

build/lib/rules/fork.js

@@ -30,2 +30,4 @@ const { fork } = require('spawncommand');
     })
+
+  let addModulesCacheLater
   if (noCache || !result) {
@@ -43,3 +45,5 @@ printed = true
     } }
-    await this.addCache('modules', cacheToWrite)
+    // post-pone setting the module cache until the fork results are got
+    // it case of cancelling the process with SIGINT
+    addModulesCacheLater = () => this.addCache('modules', cacheToWrite)
   } else {
@@ -66,3 +70,6 @@ const cache = this.getCache('fork')
   } }
-  await this.addCache('fork', cacheToWrite)
+  await Promise.all([
+    this.addCache('fork', cacheToWrite),
+    addModulesCacheLater ? addModulesCacheLater() : null,
+  ])
 
@@ -69,0 +76,0 @@ this.addAsset(mmod)

build/lib/rules/section-break.js

@@ -24,11 +24,19 @@ const { join } = require('path');
       const imgPath = join(__dirname, '../../section-breaks', name)
-      const { to, ...a } = mismatch(/(.+)="(.+)"/gm, attrs, ['key', 'val'])
+      // debugger
+      let defaultTo = '.documentary/section-breaks'
+      const { wiki } = this._args
+      if (wiki) defaultTo = join(wiki, defaultTo)
+
+      const { to, ...a } = mismatch(/(\S+)="(.+?)"/gm, attrs, ['key', 'val'])
         .reduce((acc, { key, val }) => ({ ...acc, [key]: val }), {
-          to: '.documentary/section-breaks',
+          to: defaultTo, // allow override by attributes
+          href: '#table-of-contents',
         })
 
-      const nn = `${name}?sanitize=true`
+      const nn = `${name}${wiki ? '' : '?sanitize=true'}`
       await clone(imgPath, to)
+      let fileName = join(to, nn)
+      if (fileName.startsWith(wiki)) fileName = fileName.slice(wiki.length + 1)
 
-      const tags = getTags({ src: '/' + join(to, nn), ...a })
+      const tags = getTags({ wiki, src: '/' + fileName, ...a })
       return tags
@@ -46,8 +54,16 @@ } catch (err) {
 
-const getTags = ({
-  href = '#table-of-contents',
-  ...attrs
-}) => {
-  const a = Object.keys(attrs).map(k => `${k}="${attrs[k]}"`).join(' ')
-  const s = `<p align="center"><a href="${href}"><img ${a}></a></p>`
+const getTags = ({ wiki, src, href, ...attrs }) => {
+  let a = Object.keys(attrs).map(k => {
+    const val = attrs[k]
+    if (wiki) return `${k}=${val}`
+    return `${k}="${val}"`
+  }).join(wiki ? ' ' : '|')
+  if (a) {
+    a = wiki ? `|${a}` : ` ${a}`
+  }
+
+  const img = wiki ? `
+[[${src}${a}]]
+` : `<img src="${src}"${a}>`
+  const s = `<p align="center"><a href="${href}">${img}</a></p>`
   return s
@@ -54,0 +70,0 @@ }

build/lib/Toc.js

@@ -185,2 +185,3 @@ const { Transform } = require('stream');
     })
+    if (!this.hasToc && link == 'table-of-contents') this.hasToc = true
   }
@@ -245,8 +246,12 @@
 const getToc = async (stream, h1, locations) => {
-  const toc = new Toc({ skipLevelOne: !h1, locations, documentary: stream })
+  const toc = new Toc({
+    skipLevelOne: !h1, locations, documentary: stream,
+  })
   stream.pipe(toc)
   const res = await collect(toc)
-  return res.trimRight()
+  return (toc.hasToc ? '' : tocA) + res.trimRight()
 }
 
+const tocA = '<a name="table-of-contents"></a>\n\n'
+
 /**
@@ -253,0 +258,0 @@ * @typedef {import('./typedef/Type').default} Type

build/lib/Typedefs.js

@@ -25,2 +25,10 @@ const { debuglog } = require('util');
   },
+  'http.OutgoingHttpHeaders': {
+    link: 'https://nodejs.org/api/http.html',
+    desc: 'The headers hash map for making requests, including such properties as Content-Encoding, Content-Type, etc.',
+  },
+  'http.IncomingHttpHeaders': {
+    link: 'https://nodejs.org/api/http.html',
+    desc: 'The hash map of headers that are set by the server (e.g., when accessed via IncomingMessage.headers)',
+  },
   'url.URL': {
@@ -27,0 +35,0 @@ link: 'https://nodejs.org/api/url.html#url_class_url',

CHANGELOG.md

@@ -0,1 +1,10 @@
+## 29 July 2019
+
+### [1.28.1](https://github.com/artdecocode/documentary/compare/v1.28.0...v1.28.1)
+
+- [fix] Correctly parse multiple arguments in section breaks.
+- [fix] Section breaks in Wikis.
+- [feature] Focus on wiki pages.
+- [feature] Add `#table-of-contents` anchor for Toc, if no title present.
+
 ## 26 July 2019
@@ -2,0 +11,0 @@

package.json

 {
   "name": "documentary",
-  "version": "1.28.0",
+  "version": "1.28.1",
   "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.",
@@ -25,5 +25,5 @@ "main": "build",
     "b": "yarn-s src jsx b2",
-    "src": "alamode-depack src -o build -i bin/index.js -s",
-    "jsx": "alamode-depack build/components -o build/components -s -j -p",
-    "b2": "alamode-depack build/components -o build/components -s",
+    "src": "alamode src -o build -i bin/index.js -s",
+    "jsx": "alamode build/components -o build/components -s -j -p",
+    "b2": "alamode build/components -o build/components -s",
     "build": "yarn-s b doc",
@@ -96,3 +96,3 @@ "args": "argufy types/arguments.xml -o src/bin/get-args.js"
     "@wrote/write": "^1.0.4",
-    "alamode": "^2.3.4",
+    "alamode": "^2.3.6",
     "argufy": "^1.7.1",
@@ -109,6 +109,6 @@ "catchment": "^3.3.0",
     "restream": "^3.7.2",
-    "rexml": "^2.0.2",
+    "rexml": "^2.0.3",
     "spawncommand": "^2.2.0",
     "static-analysis": "^1.7.1",
-    "typal": "^1.16.0",
+    "typal": "^1.17.0",
     "usually": "^1.2.0",
@@ -115,0 +115,0 @@ "which-stream": "^1.1.0"

New alerts

License Policy Violation

License

This 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

License

This 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

206972

increased by2.07%

Lines of code

3140

increased by2.35%

Number of lines in readme file

1572

increased by1.35%

Dependency changes

• Updatedalamode@^2.3.6

• Updatedrexml@^2.0.3

• Updatedtypal@^1.17.0