Skip to content

Latest commit

 

History

History
580 lines (499 loc) · 17.8 KB

README.md

File metadata and controls

580 lines (499 loc) · 17.8 KB
Raw

@blockquote/to-markdown

Individual NPM package from the following PR

Custom-elements.json is a file format that describes custom elements. This format will allow tooling and IDEs to give rich information about the custom elements in a given project. It is, however, very experimental and things are subject to change. Follow the discussion here.

This library takes a Custom Elements Manifest and renders it to markdown.

Usage

Install:

npm i -S @blockquote/to-markdown

Import and use in your code:

import fs from 'fs';
import { customElementsManifestToMarkdown } from '@blockquote/to-markdown';

const manifest = JSON.parse(fs.readFileSync('./custom-elements.json', 'utf-8'));
const markdown = customElementsManifestToMarkdown(manifest);

fs.writeFileSync('./custom-elements.md', markdown);

Options

Option Type Default Description
headingOffset Integer 0 Offset the heading level by this number
mainDescription Boolean true Show description field for Class and Mixins
private 'all'|'details'|'hidden' 'all' See Private Members
omitDeclarations OptionalDeclarations[] [] See Omit Declarations
omitSections OptionalSections[] [] See Omit Sections
classNameFilter string | (() => string) '.*' See Class Name Filter

Private Members

The private option controls how private members appear in the markdown.

  • 'all': private members appear alongside public members according to source order
  • 'hidden': private members do not appear at all in markdown, but protected members do
  • 'details': private and protected members appear in a details disclosure widget below the table

Omit Declarations

The omitDeclarations option is a string[] that controls which kinds of entities are rendered in the final markdown output. The four declaration types are:

  • mixins
  • variables
  • functions
  • exports

The following is an example config that would filter out all four declaration types:

customElementsManifestToMarkdown(manifest, {
  omitDeclarations: ['mixins', 'variables', 'functions', 'exports' ]
})

**Note: ** Mixins can be rendered both as declarations AND as sections inside a declaration. The omitDeclarations option for mixins will only filter out top level mixin declarations. To filter out mixin sections from a class declaration, use the mixin filter from omitSections.

Omit Sections

The omitSections option is a string[] that controls which sections of a declaration's full entry in the manifest.json should be rendered in the final markdown output. The section names are:

  • mainHeading : "main-heading"
  • mainDescription : "main-description"
  • superClass : "super-class"
  • fields : "fields"
  • methods : "methods"
  • staticFields : "static-fields"
  • staticMethods : "static-methods"
  • slots : "slots"
  • events : "events"
  • attributes : "attributes"
  • cssProperties : "css-properties"
  • cssParts : "css-parts"
  • mixins : "main-heading"

The following is an example config showing how to filter out a few sections:

customElementsManifestToMarkdown(manifest, {
  // static fields and static methods tables will not be present
  // in the markdown result
  omitSections: [ 'super-class', 'static-methods', 'fields' ]
})

Class Name Filter

Depending on the source files you pass to the analyzer, your custom-elements-manifest.json may contain more class file declarations than you need for the final markdown output. The classNameFilter option accepts a regex as a string (or a function that returns one) that will be used to filter out class declarations before rendering.

customElementsManifestToMarkdown(manifest, {
  classNameFilter: () => {
    // some logic
    return `(${prefix}-*|SuperClassExact)`; // filters out every class name that doesnt match the regex provided
  }
})

Demo

customElementsManifestToMarkdown(manifest, {
  headingOffset: 1,
  private: 'details',
})
Source 
{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "./fixtures/-TEST/package/my-element.js",
      "declarations": [
        {
          "kind": "class",
          "description": "My description",
          "name": "SuperClass",
          "events": [
            {
              "name": "custom-event",
              "type": {
                "text": "SuperCustomEvent"
              },
              "description": "this is custom"
            }
          ],
          "superclass": {
            "name": "LitElement",
            "package": "lit-element"
          },
          "members": [
            {
              "kind": "method",
              "name": "superClassMethod",
              "privacy": "public"
            }
          ]
        },
        {
          "kind": "class",
          "name": "MyElement",
          "cssProperties": [
            {
              "name": "--background-color",
              "description": "Controls the color of bar"
            }
          ],
          "cssParts": [
            {
              "name": "bar",
              "description": "Styles the color of bar"
            }
          ],
          "slots": [
            {
              "name": "container",
              "description": "You can put some elements here"
            }
          ],
          "events": [
            {
              "name": "my-event",
              "type": {
                "text": "Event"
              }
            },
            {
              "name": "custom-event",
              "type": {
                "text": "SuperCustomEvent"
              },
              "description": "this is custom",
              "inheritedFrom": {
                "name": "SuperClass",
                "module": "./fixtures/-TEST/package/my-element.js"
              }
            }
          ],
          "mixins": [
            {
              "name": "LocalizeMixin",
              "package": "lion"
            },
            {
              "name": "Mixin",
              "module": "./fixtures/-TEST/package/my-element.js"
            }
          ],
          "superclass": {
            "name": "SuperClass",
            "module": "./fixtures/-TEST/package/my-element.js"
          },
          "attributes": [
            {
              "name": "prop-1",
              "fieldName": "prop1"
            },
            {
              "name": "prop2",
              "fieldName": "prop2"
            }
          ],
          "members": [
            {
              "kind": "field",
              "name": "prop1",
              "privacy": "public"
            },
            {
              "kind": "field",
              "name": "prop2",
              "privacy": "public"
            },
            {
              "kind": "field",
              "name": "prop3",
              "privacy": "public",
              "type": {
                "text": "boolean"
              },
              "default": "true"
            },
            {
              "kind": "field",
              "name": "foo",
              "type": {
                "text": "string"
              },
              "privacy": "private",
              "description": "description goes here",
              "default": "'bar'"
            },
            {
              "kind": "method",
              "name": "instanceMethod",
              "privacy": "public",
              "description": "Some description of the method here",
              "return": {
                "type": {
                  "text": ""
                }
              },
              "parameters": [
                {
                  "name": "e",
                  "type": {
                    "text": "Event"
                  }
                },
                {
                  "name": "a",
                  "type": {
                    "text": "string"
                  },
                  "description": "some description"
                }
              ]
            },
            {
              "kind": "field",
              "name": "mixinProp",
              "type": {
                "text": "number"
              },
              "privacy": "protected",
              "default": "1",
              "inheritedFrom": {
                "name": "Mixin",
                "module": "./fixtures/-TEST/package/my-element.js"
              }
            },
            {
              "kind": "method",
              "name": "superClassMethod",
              "privacy": "public",
              "inheritedFrom": {
                "name": "SuperClass",
                "module": "./fixtures/-TEST/package/my-element.js"
              }
            }
          ],
          "tagName": "my-element"
        },
        {
          "kind": "variable",
          "name": "variableExport",
          "description": "this is a var export",
          "type": {
            "text": "boolean"
          }
        },
        {
          "kind": "variable",
          "name": "stringVariableExport",
          "description": "this is a string var export",
          "type": {
            "text": "string"
          }
        },
        {
          "kind": "function",
          "name": "functionExport",
          "description": "This is a function export",
          "return": {
            "type": {
              "text": "boolean"
            }
          },
          "parameters": [
            {
              "name": "a",
              "type": {
                "text": "string"
              }
            },
            {
              "name": "b",
              "type": {
                "text": "boolean"
              }
            }
          ]
        },
        {
          "kind": "mixin",
          "name": "MyMixin4",
          "parameters": [
            {
              "name": "klass",
              "type": {
                "text": "*"
              },
              "description": "This is the description"
            },
            {
              "name": "foo",
              "type": {
                "text": "string"
              },
              "description": "Description goes here"
            }
          ]
        },
        {
          "kind": "mixin",
          "name": "Mixin",
          "parameters": [
            {
              "name": "klass",
              "type": {
                "text": "*"
              },
              "description": "This is the description"
            }
          ],
          "members": [
            {
              "kind": "field",
              "name": "mixinProp",
              "type": {
                "text": "number"
              },
              "privacy": "protected",
              "default": "1"
            }
          ]
        }
      ],
      "exports": [
        {
          "kind": "js",
          "name": "SuperClass",
          "declaration": {
            "name": "SuperClass",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        },
        {
          "kind": "custom-element-definition",
          "name": "my-element",
          "declaration": {
            "name": "MyElement",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        },
        {
          "kind": "js",
          "name": "variableExport",
          "declaration": {
            "name": "variableExport",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        },
        {
          "kind": "js",
          "name": "stringVariableExport",
          "declaration": {
            "name": "stringVariableExport",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        },
        {
          "kind": "js",
          "name": "functionExport",
          "declaration": {
            "name": "functionExport",
            "module": "./fixtures/-TEST/package/my-element.js"
          }
        }
      ]
    }
  ]
}
Result

My description

./fixtures/-TEST/package/my-element.js:

class: SuperClass

Superclass

Name Module Package
LitElement lit-element

Methods

Name Privacy Description Parameters Return Inherited From
superClassMethod public

Events

Name Type Description Inherited From
custom-event SuperCustomEvent this is custom

class: MyElement, my-element

Superclass

Name Module Package
SuperClass ./fixtures/-TEST/package/my-element.js

Mixins

Name Module Package
LocalizeMixin lion
Mixin ./fixtures/-TEST/package/my-element.js

Fields

Name Privacy Type Default Description Inherited From
prop1 public
prop2 public
prop3 public boolean true

Methods

Name Privacy Description Parameters Return Inherited From
instanceMethod public Some description of the method here e: Event, a: string
superClassMethod public SuperClass

Events

Name Type Description Inherited From
my-event Event
custom-event SuperCustomEvent this is custom SuperClass

Attributes

Name Field Inherited From
prop-1 prop1
prop2 prop2

CSS Properties

Name Description
--background-color Controls the color of bar

Slots

Name Description
container You can put some elements here
Private API

Fields

Name Privacy Type Default Description Inherited From
foo private string 'bar' description goes here
mixinProp protected number 1 Mixin

mixin: MyMixin4

Parameters

Name Type Default Description
klass * This is the description
foo string Description goes here

mixin: Mixin

Parameters

Name Type Default Description
klass * This is the description
Private API

Fields

Name Privacy Type Default Description Inherited From
mixinProp protected number 1

Variables

Name Description Type
variableExport this is a var export boolean
stringVariableExport this is a string var export string

Functions

Name Description Parameters Return
functionExport This is a function export a: string, b: boolean boolean

Exports

Kind Name Declaration Module Package
js SuperClass SuperClass ./fixtures/-TEST/package/my-element.js
custom-element-definition my-element MyElement ./fixtures/-TEST/package/my-element.js
js variableExport variableExport ./fixtures/-TEST/package/my-element.js
js stringVariableExport stringVariableExport ./fixtures/-TEST/package/my-element.js
js functionExport functionExport ./fixtures/-TEST/package/my-element.js