documentary - npm Package Compare versions

Comparing version 1.35.0 to 1.35.1

build/components/index.js

 const { h } = require('preact');
 const { makeMethodTable } = require('./Typedef/lib');
-const { relative, dirname } = require('path');
+const { makeLinking } = require('./Typedef');
+const { getLink } = require('../lib');
 
@@ -22,2 +23,3 @@ const $_shell = require('./shell');
 /**
+ * The method for adding a heading and description of a method inside a constructor/interface.
  * @param {Object} params
@@ -50,27 +52,48 @@ * @param {import('../lib/Documentary').default} params.documentary
   const {
-    _args: { wiki, source }, currentFile,
+    _args: { wiki, source }, currentFile, error,
   } = documentary
   const file = wiki ? source : currentFile
-  const linking = ({ link, type: refType }) => {
-    // when splitting wiki over multiple pages, allows
-    // to create links to the exact page.
-    const l = `#${link}`
-    // semi-hack
-    if (refType.appearsIn.includes(file)) return l
-    const ai = refType.appearsIn[0]
-    let rel = relative(dirname(file), ai)
-    if (wiki) rel = rel.replace(/\.(md|html)$/, '')
-    return `${rel}${l}`
-  }
+  const linking = makeLinking(wiki, file)
   if (justHeading) return res
   let table = ''
   try {
-    table = makeMethodTable(prop, documentary.allTypes, {
+    table = makeMethodTable(prop, documentary.allTypesWithIncluded, {
       link: linking,
-    })
+      flatten(n) {
+        // debugger
+        // flattened[n] = true
+      },
+    }, { wiki })
   } catch (err) {
-    console.warn(err.message)
+    error(err)
   }
   return [res, table].filter(Boolean).join('\n\n')
 }
+
+/**
+ * The method for adding a heading and description of a method inside a constructor/interface.
+ * @param {Object} params
+ * @param {import('../lib/Documentary').default} params.documentary
+ */
+function link({ documentary, type, children }) {
+  documentary.pretty(false)
+  const foundType = documentary.allTypesWithIncluded.find(({ fullName }) => {
+    return fullName == type
+  })
+  if (!foundType) throw new Error(`Type ${type} not found.`)
+
+  const {
+    _args: { wiki, source }, currentFile, error,
+  } = documentary
+  const file = wiki ? source : currentFile
+  const linking = makeLinking(wiki, file, error)
+
+  if (foundType.link) {
+    return (h('a',{'href':foundType.link, 'title':foundType.description},children))
+  }
+  const l = getLink(foundType.fullName, 'type')
+  const ll = linking({ link: l, type: foundType })
+  return (h('a',{'href':ll, 'title':foundType.description},children))
+}
+
 // export { default as method } from './method'
@@ -80,2 +103,3 @@ // export { default as method } from './Method/index'
 module.exports.method = method
+module.exports.link = link
 module.exports.shell = $_shell
@@ -82,0 +106,0 @@ module.exports.argufy = $_Argufy

build/components/Typedef/index.js

@@ -19,3 +19,3 @@ const { h } = require('preact');
 
-const makeLinking = (wiki, file) => {
+const makeLinking = (wiki, file, error = () => {}) => {
   const linking = ({ link, type: refType }) => {
@@ -32,2 +32,3 @@ // when splitting wiki over multiple pages, allows
     const ai = appearsIn[0] //
+    if (!ai) error(new Error('appearsIn is empty'))
     let rel = relative(dirname(file), ai)
@@ -49,9 +50,7 @@ if (wiki) rel = rel.replace(/\.(md|html)$/, '')
   const {
-    locations, allTypes, cut: { code: cutCode },
-    _args: { wiki, source }, currentFile, _typedefs,
+    locations, allTypesWithIncluded, cut: { code: cutCode },
+    _args: { wiki, source }, currentFile,
   } = documentary
   const file = wiki ? source : currentFile
 
-  const at = [...allTypes, ..._typedefs.included]
-
   documentary.setPretty(false)
@@ -85,3 +84,3 @@ let [location] = children
     if (!type.isMethod) {
-      const res = type.toMarkdown(at, opts)
+      const res = type.toMarkdown(allTypesWithIncluded, opts)
       if (level) res.LINE = res.LINE.replace(/t-type/, `${'#'.repeat(level)}-type`)
@@ -91,3 +90,3 @@ return res
     const LINE = Method({ documentary, level, method: type, noArgTypesInToc })
-    const table = makeMethodTable(type, at, opts)
+    const table = makeMethodTable(type, allTypesWithIncluded, opts, { wiki })
     return { LINE, table, examples: type.examples }
@@ -100,3 +99,3 @@ })
 
-  const j = importsToMd.map(i => i.toMarkdown(at, { flatten }))
+  const j = importsToMd.map(i => i.toMarkdown(allTypesWithIncluded, { flatten }))
 
@@ -107,5 +106,5 @@ const ttt = tt.map((s, i) => {
 
-    const ch = isObject ?       h(Narrow,{...type,key:i,
-      documentary:documentary, allTypes:at, opts:opts,
-      slimFunctions:slimFunctions
+    const ch = isObject ?        h(Narrow,{...type,key:i,
+      documentary:documentary, allTypes:allTypesWithIncluded, opts:opts,
+      slimFunctions:slimFunctions, wiki:wiki
     }) : type
@@ -146,3 +145,3 @@ if (displayInDetails) {
 const Narrow = ({ props, anyHaveDefault, documentary, constr, allTypes, opts,
-  slimFunctions }) => {
+  slimFunctions, wiki }) => {
   const md = (name, afterCutLinks) => {
@@ -160,3 +159,3 @@ return md2html({ documentary, children: [name], afterCutLinks })
       let desc = (prop.args && !slimFunctions) ? makeMethodTable(prop, allTypes, opts, {
-        indent: '', join: '<br/>\n', preargs: '<br/>\n',
+        indent: '', join: '<br/>\n', preargs: '<br/>\n', wiki,
       }) : de
@@ -163,0 +162,0 @@ let hasCodes

build/components/Typedef/lib.js

 const { h } = require('preact');
 const { getLinks } = require('typal');
+const { clone } = require('../../../stdlib');
+const { basename, dirname, join: joinPath } = require('path');
 
@@ -7,6 +9,6 @@ /**
  * @param {Array<import('typal/types').Type>} allTypes
- * @param {import('typal/types').LinkingOptions} linkingOpts
+ * @param {import('typal/types').LinkingOptions} [linkingOpts]
  */
-const makeMethodTable = (method, allTypes = [], linkingOpts, {
-  indent = ' - ', join = '\n', preargs = '\n\n',
+const makeMethodTable = (method, allTypes = [], linkingOpts = {}, {
+  indent = ' - ', join = '\n', preargs = '\n\n', wiki,
 } = {}) => {
@@ -20,3 +22,19 @@ let table = method.description || ''
       , useCode = false
-    typeWithLink = getLinks(allTypes, type, linkingOpts)
+    typeWithLink = getLinks(allTypes, type, {
+      ...linkingOpts,
+      nameProcess(n) {
+        const nn = n.replace('!', '')
+        const found = allTypes.find(({ fullName }) => fullName == nn)
+
+        if (!found) return n
+        const { icon, iconAlt = 'Type Icon' } = found
+        if (!icon) return n
+        let iconPath = joinPath('.documentary', 'type-icons', basename(icon))
+        const to = wiki ? joinPath(wiki, iconPath) : iconPath
+        clone(icon, dirname(to))
+        const s = `<img src="${iconPath}" alt="${iconAlt}">${n}`
+        // debugger
+        return s
+      },
+    })
     useCode = typeWithLink != type
@@ -23,0 +41,0 @@ typeWithLink = wrapCode(typeWithLink, useCode)

build/lib/components.js

@@ -20,3 +20,3 @@ const { c, b } = require('../../stdlib');
      */
-    getProps(htmlProps, meta) {
+    getProps(htmlProps, meta, name) {
       meta.setPretty(true, 100)
@@ -32,2 +32,5 @@ const d = getDocumentary()
           }
+          if (p == 'pretty') {
+            return meta.setPretty
+          }
           if (p == 'removeLine') {
@@ -39,2 +42,9 @@ return () => {
           }
+          if (p == 'error') {
+            return (err) => {
+              const stack = err.stack.replace(err.message, '')
+              console.error(b(`<${name}>`, 'yellow'), c(err.message, 'red'))
+              console.error(c(stack, 'grey'))
+            }
+          }
           return target[p]
@@ -41,0 +51,0 @@ },

build/lib/Documentary.js

@@ -256,4 +256,5 @@ const { Replaceable, makeMarkers, makeCutRule, makePasteRule } = require('../../stdlib');
     if (this._typedefs) {
+      // update imports
       const imports = this._typedefs.types.filter(({ import: i }) => i)
-      this._typedefs.included.forEach(({ description, fullName: k, link }) => {
+      this._typedefs.included.forEach(({ description, fullName: k, link, icon, iconAlt }) => {
         const i = imports.find(({ fullName }) => fullName == k)
@@ -263,2 +264,4 @@ if (!i) return
         if (!i.description) i.description = description
+        if (!i.icon) i.icon = icon
+        if (!i.iconAlt) i.iconAlt = iconAlt
       })
@@ -283,2 +286,12 @@ }
   }
+  /**
+   * The list of types also with types from typedefs.json
+   */
+  get allTypesWithIncluded() {
+    const { _typedefs } = this
+    if (_typedefs) {
+      return [..._typedefs.types, ..._typedefs.included]
+    }
+    return []
+  }
 
@@ -285,0 +298,0 @@ /**

build/lib/Typedefs.js

@@ -190,3 +190,3 @@ const { Replaceable, replace } = require('../../stdlib');
     },
-    'include-typedefs'({ children }) {
+    'include-typedefs'({ children, icon, 'icon-alt': iconAlt }) {
       let [loc] = children
@@ -202,2 +202,3 @@ loc = loc.trim() || 'typedefs.json'
           description,
+          icon, iconAlt,
         }
@@ -226,4 +227,6 @@ this.included.push(t)
   })
-  t.write({ data: `<include-typedefs>
-    ${resolve(__dirname, '../../typedefs.json')}
+  const nodeTypedefs = resolve(__dirname, '../../typedefs.json')
+  const nodeIcon = resolve(__dirname, '../node.png')
+  t.write({ data: `<include-typedefs icon="${nodeIcon}" icon-alt="Node.JS Docs">
+    ${nodeTypedefs}
   </include-typedefs>`, file: 'fake.md' })
@@ -230,0 +233,0 @@ stream.pipe(t).pipe(typedefs)

CHANGELOG.md

 ## 19 December 2019
 
+### [1.35.1](https://github.com/artdecocode/documentary/compare/v1.35.0...v1.35.1)
+
+- [feature] _Node.JS_ logo for methods.
+- [api] Add `error` property to _Documentary_ in components.
+- [feature] Add `<link>` component for types' linking.
+
 ### [1.35.0](https://github.com/artdecocode/documentary/compare/v1.34.11...v1.35.0)
@@ -4,0 +10,0 @@

package.json

 {
   "name": "documentary",
-  "version": "1.35.0",
+  "version": "1.35.1",
   "description": "Documentation Compiler 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.",
@@ -5,0 +5,0 @@ "main": "build",

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

460015

increased by0.69%

Number of package files

79

increased by1.28%

Lines of code

5020

increased by1.27%

No dependency changes