Documenting dependencies when run from incorrect directory structure

[mmm111mmm]

If you have a directories like:

• your_component/index.html
• your_component/your_component.html
• your_component/bower_components/depenencies...

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]

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

[arthurevans]

@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]

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

[mmm111mmm]

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

• I have a base directory.
• In that directory I have my some-element.html
• And I have an index.html page where I call the some-element.
• And I have bower_components/ with all my dependencies in the base directory

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]

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]

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.