|
| 1 | +[](https://travis-ci.org/PolymerElements/iron-component-page) |
| 2 | +[](https://beta.webcomponents.org/element/PolymerElements/iron-component-page) |
1 | 3 |
|
2 | | -<!--- |
| 4 | +## <iron-component-page> |
3 | 5 |
|
4 | | -This README is automatically generated from the comments in these files: |
5 | | -iron-component-page.html |
| 6 | +*** |
| 7 | +⚠️ The version of `iron-component-page` described below is coming soon, but not |
| 8 | +quite yet tagged for release. You can checkout the `master` branch to |
| 9 | +experiment with it now. See [this |
| 10 | +issue](https://github.com/PolymerElements/iron-component-page/issues/121) for |
| 11 | +status. ⚠️ |
| 12 | +*** |
6 | 13 |
|
7 | | -Edit those files, and our readme bot will duplicate them over here! |
8 | | -Edit this file, and the bot will squash your changes :) |
| 14 | +`iron-component-page` is a full-page documentation browser for custom elements, |
| 15 | +mixins, classes, and more. It consumes the JSON descriptor format produced by |
| 16 | +[Polymer Analyzer](https://github.com/Polymer/polymer-analyzer). |
9 | 17 |
|
10 | | -The bot does some handling of markdown. Please file a bug if it does the wrong |
11 | | -thing! https://github.com/PolymerLabs/tedium/issues |
| 18 | +You may also be interested in the |
| 19 | +[`iron-doc-*`](https://github.com/PolymerElements/iron-doc-viewer) element |
| 20 | +collection which underlies this element and can be used to embed documentation |
| 21 | +in other apps (for example, [webcomponents.org](https://wwww.webcomponents.org) |
| 22 | +does this). |
12 | 23 |
|
13 | | ---> |
| 24 | +### Documenting your element |
14 | 25 |
|
15 | | -[](https://travis-ci.org/PolymerElements/iron-component-page) |
| 26 | +`iron-component-page` is designed to make it easy to view documentation for |
| 27 | +your custom element project. |
16 | 28 |
|
17 | | -_[Demo and API docs](https://elements.polymer-project.org/elements/iron-component-page)_ |
| 29 | +1. Install the [Polymer CLI](https://github.com/Polymer/polymer-cli) with `npm |
| 30 | + install -g polymer-cli` or `yarn global add polymer-cli`. This gives you a |
| 31 | + command-line interface to Polymer Analyzer (among other things). |
18 | 32 |
|
| 33 | +2. `cd` to your project directory. This can be a custom element, a full app, or |
| 34 | + even a plain JavaScript library. Polymer Analyzer will discover all of the |
| 35 | + interesting items recursively in your project directory. |
19 | 36 |
|
20 | | -## <iron-component-page> |
| 37 | +3. Analyze your project with `polymer analyze > analysis.json`. This produces a |
| 38 | + JSON descriptor file. By default `iron-component-page` will look for a file |
| 39 | + called `analysis.json` (you can override this with the `descriptor-url` |
| 40 | + property). |
| 41 | + |
| 42 | +4. Add `iron-component-page` as a dev dependency of your project: `bower |
| 43 | + install iron-component-page --save-dev`. |
| 44 | + |
| 45 | +5. Create an HTML file to instantiate an `iron-component-page` element (e.g. |
| 46 | + `index.html` or `docs.html`). Note that you may need to adjust your import |
| 47 | + paths depending on your project layout: |
| 48 | + |
| 49 | +```html |
| 50 | +<!doctype html> |
| 51 | +<html> |
| 52 | +<head> |
| 53 | + <meta charset="utf-8"> |
| 54 | + <meta name="viewport" content="width=device-width, minimum-scale=1.0, initial-scale=1.0, user-scalable=yes"> |
| 55 | + <script src="/bower_components/webcomponentsjs/webcomponents-loader.js"></script> |
| 56 | + <link rel="import" href="/bower_components/iron-component-page/iron-component-page.html"> |
| 57 | +</head> |
| 58 | +<body> |
| 59 | + <iron-component-page></iron-component-page> |
| 60 | +</body> |
| 61 | +</html> |
| 62 | +``` |
| 63 | + |
| 64 | +6. Serve that page using any local web server, such as `polymer serve` or |
| 65 | + `python -m SimpleHTTPServer`. |
| 66 | + |
| 67 | +### Routing |
| 68 | + |
| 69 | +`iron-component-page` handles URL routing (via `iron-doc-viewer`) to provide |
| 70 | +permanent addresses for all locations in the documentation tree, including |
| 71 | +scroll anchor targets. |
| 72 | + |
| 73 | +By default it uses the URL fragment for routing (e.g. |
| 74 | +`docs.html#/elements/my-element#property-foo`), in order to support simple |
| 75 | +static file hosts. |
| 76 | + |
| 77 | +To use the real URL path for routing, set the `base-href` property to the |
| 78 | +server mount point (e.g. `/` or `/docs/`). Note that this requires a host that |
| 79 | +serves the application from all paths that should be handled by the doc viewer. |
| 80 | + |
| 81 | +### Previous versions |
21 | 82 |
|
22 | | -Loads Polymer element and behavior documentation using |
23 | | -[Hydrolysis](https://github.com/PolymerLabs/hydrolysis) and renders a complete |
24 | | -documentation page including demos (if available). |
| 83 | +The 3.x `iron-component-page` described here has major breaking changes versus |
| 84 | +the 1.x and 2.x versions. Previous versions were based on *Hydrolysis*, the |
| 85 | +predecessor to Polymer Analyzer. Major changes in the 3.x version include: |
25 | 86 |
|
| 87 | +* Uses Polymer Analyzer descriptors instead of Hydrolysis. Among other things, |
| 88 | + this adds support for classes, mixins, and Polymer 2 elements. |
| 89 | +* Does not analyze your source in the browser. Instead, run `polymer analyze` |
| 90 | + to generate an `analysis.json` file offline. |
| 91 | +* Replaces the element menu with a full-size navigation panel that summarizes |
| 92 | + all the available documentation produced by Polymer Analyzer. |
26 | 93 |
|
| 94 | +If you still need the previous version, see the |
| 95 | +[2.x branch](https://github.com/PolymerElements/iron-component-page/tree/2.x). |
0 commit comments