PolymerElements / iron-component-page

A reusable landing page for elements
36 stars 32 forks source link

Documenting dependencies when run from incorrect directory structure #89

Open mmm111mmm opened 8 years ago

mmm111mmm commented 8 years ago

If you have a directories like:

And you run iron-component-page from index.html, and in your your_component.html you reference your dependencies like bower_components/iron-image/iron-image.html, then the resulting documentation will include all your dependencies, including polymer itself.

When, however, you move your component to your_component/bower_components/your_component /and change the dependencies paths to ../iron-image/iron-image then it works as expected: we only document the elements in your_component.html.

Can this please be made explicit in the documentation and the article at https://www.polymer-project.org/1.0/tools/documentation.html ? Because it's not at the moment. And it causes pain, much pain.

justinfagnani commented 8 years ago

@arthurevans should I file a doc bug, or make PR? I'm not sure how the docs are built.

arthurevans commented 8 years ago

@justinfagnani Either one will do. I'm having trouble following the issue description, so if you can help with a description or PR, that'd be great.

It sounds like maybe the confusion is due to not using the seed-element structure or not using polyserve to preview docs locally?

justinfagnani commented 8 years ago

Yes, sounds like iron-component-page expects the reusable component structure.

mmm111mmm commented 8 years ago

To clarify, I'm of the habit of writing components like this:

If I call the iron-component-page from index.html, it documents all my dependencies including Polymer etc.

I've no problem with restructuring my folder structure. I'd just like to be told to do so, instead of having to find out.

justinfagnani commented 8 years ago

I don't think it's where the files are, but what the import URLs look like. In some-element.html, the import URLs to other bower components should look like: ../other-element/other-element.html. You shouldn't actually need to put you element in bower_components/, polyserve make it look like that to the browser for you.

mmm111mmm commented 8 years ago

Ah right. Yes, that makes more sense.

In my deviant structure, I'm importing via bower_components/iron-image/iron-image.html instead of ../iron-image/iron-image.html.