Polymer documentation viewer elements
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.github Create CODEOWNERS Jan 24, 2018
demo Update README. Jul 10, 2018
test Fix formatting. Aug 21, 2018
.gitignore
.npmignore
.travis.yml Only generate types once on Travis Sep 7, 2018
CONTRIBUTING.md [skip ci] Update contribution guide May 17, 2016
README.md Fix webcomponents.org link Jul 10, 2018
bower.json Add `bower.json` so that webcomponents.org can read the repo. Sep 14, 2018
default-theme.js Prepare 3.0 final Jun 27, 2018
formatconfig.json Fix formatconfig.json Aug 8, 2018
iron-doc-api.js Remove `=""` from boolean attributes. Aug 7, 2018
iron-doc-behavior.js Remove `=""` from boolean attributes. Aug 7, 2018
iron-doc-class.js
iron-doc-demo.js Prepare 3.0 final Jun 27, 2018
iron-doc-element.js Remove `=""` from boolean attributes. Aug 7, 2018
iron-doc-function.js Remove `=""` from boolean attributes. Aug 7, 2018
iron-doc-hide-bar.js
iron-doc-mixin.js Remove `=""` from boolean attributes. Aug 7, 2018
iron-doc-module.js
iron-doc-namespace.js Remove `=""` from boolean attributes. Aug 7, 2018
iron-doc-nav.js Prepare 3.0 final Jun 27, 2018
iron-doc-property.js Remove `=""` from boolean attributes. Aug 7, 2018
iron-doc-summary.js Prepare 3.0 final Jun 27, 2018
iron-doc-viewer-behavior.js Prepare 3.0 final Jun 27, 2018
iron-doc-viewer-styles.js Prepare 3.0 final Jun 27, 2018
iron-doc-viewer.js Remove a reference to HTML imports from the docs. Aug 17, 2018
manifest.json auto-converted by polymer-modulizer Jun 23, 2018
package-lock.json 4.0.1 Sep 14, 2018
package.json 4.0.1 Sep 14, 2018
wct.conf.json Update WCT config Jun 5, 2018

README.md

Published on NPM Build status Published on webcomponents.org

<iron-doc-viewer>

A collection of elements that display documentation about custom elements, mixins, classes, and more using the JSON descriptor format produced by Polymer Analyzer.

See: Documentation, Demo.

You may also be interested in <iron-component-page>, which composes the iron-doc elements into a more complete documentation browser.

Elements

  • <iron-doc-nav> Show a table-of-contents.
  • <iron-doc-viewer> Manage routing and delegate to a child doc element.
  • <iron-doc-element> Show docs about a custom element.
  • <iron-doc-behavior> Show docs about a Polymer behavior.
  • <iron-doc-namespace> Show docs about a JavaScript namespace.
  • <iron-doc-class> Show docs about a JavaScript class.
  • <iron-doc-mixin> Show docs about a JavaScript mixin.

Usage

Installation

npm install --save @polymer/iron-doc-viewer

In an html file

<html>
  <head>
    <script type="module">
      import '@polymer/polymer/lib/elements/dom-bind.js';
      import '@polymer/iron-ajax/iron-ajax.js';
      import '@polymer/iron-doc-viewer/iron-doc-viewer.js';
    </script>
  </head>

  <body>
    <dom-bind>
      <template>
        <iron-ajax
          auto
          url="./analysis.json"
          last-response="{{descriptor}}">
        </iron-ajax>

        <iron-doc-viewer
          descriptor="[[descriptor]]"
          root-namespace="MyNamespace">
        </iron-doc-viewer>
      </template>
    </dom-bind>
  </body>
</html>

In a Polymer 3 element

import {PolymerElement, html} from '@polymer/polymer';
import '@polymer/iron-doc-viewer/iron-doc-viewer.js';

class SampleElement extends PolymerElement {
  static get template() {
    return html`
      <iron-doc-viewer
        descriptor="[[descriptor]]"
        root-namespace="MyNamespace">
      </iron-doc-viewer>
    `;
  },

  static get properties() {
    return {
      descriptor: {
        type: Object,
        value: {
          // Analyzer descriptor goes here.
        }
      }
    };
  }
}

customElements.define('sample-element', SampleElement);

Routing

<iron-doc-viewer> handles URL routing to provide permanent addresses for all locations in the documentation tree, including scroll anchor targets.

By default it uses the URL fragment for routing (e.g. docs.html#/elements/my-element#property-foo), in order to support simple static file hosts.

To use the real URL path for routing, set the base-href property to the server mount point, omitting the trailing slash (e.g. /api/docs or empty string for the root path). Note that this requires a host that serves the application from all paths that should be handled by the doc viewer.

Styling

The iron-doc elements come with an optional material-design default theme that must be explicitly included as custom style:

<script type="module">
  import '@polymer/iron-doc-viewer/default-theme.js';
</script>

<custom-style>
  <style is="custom-style" include="iron-doc-default-theme"></style>
</custom-style>

The following custom properties and mixins are available for styling:

Custom property Description Default
--iron-doc-accent-color Color for emphasis (e.g. hyperlink hover). #1565c0
--iron-doc-font-body Mixin applied to non-code text. {}
--iron-doc-font-code Mixin applied to code snippets. {}
--iron-doc-title Mixin applied to page titles. {}
--iron-doc-heading Mixin applied to section headings. {}

Contributing

If you want to send a PR to this element, here are the instructions for running the tests and demo locally:

Installation

git clone https://github.com/PolymerElements/iron-doc-viewer
cd iron-doc-viewer
npm install
npm install -g polymer-cli

Running the demo locally

polymer serve --npm
open http://127.0.0.1:<port>/demo/

Running the tests

polymer test --npm