search

dart-lang / dartdoc

API documentation tool for Dart.
https://pub.dev/packages/dartdoc
BSD 3-Clause "New" or "Revised" License
473 stars 119 forks source link

Page styles and links broken on angular_components StepDirective page #1721

Open chalin opened 6 years ago

chalin commented 6 years ago

The Problem

Visiting https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective results in an unstyled page:

screen shot 2018-07-04 at 11 22 35

The problem is that the page contains <base href="../.."> but the style files are at ...

Why its happening

The cause of the problem is that StepDirective has a field named index, and so the API doc page for this field is index.html. A get request for

One might argue that we shouldn't be attempting to access https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective, but it isn't that simple as I explain next.

API docs on webdev.dartlang.org

For a server configured to support clean URLs w/o trailing slashes, a request for

Solution ideas

A possible solution might be to have a dartdoc option in support of doc servers configured with clean URLs and no trailing slashes. This option would ensure that the base href for API pages named index.html gets set to .. rather than ../...

Another option might be to set the base href dynamically, but that might get tricky.

Note that in the meantime I've been manually patching the generated API docs, setting the base href to a proper value.

cc @kwalrath @kevmoo @nshahan

jcollins-g commented 6 years ago

Another possibility is to never create index.html files and instead use a special, non-colliding name in this case. IIUC that would create the desired behavior (404 not found for https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective) while still allowing us to link to the index property elsewhere.

Dartdoc already does some special things to avoid collisions in naming files so this isn't that outrageous, but it might be one of the first user-visible changes to the linking strategy.

chalin commented 6 years ago

Another possibility is to never create index.html files and instead use a special, non-colliding name in this case.

Interesting proposal.

IIUC that would create the desired behavior

Yes.

it might be one of the first user-visible changes to the linking strategy

Ah, well, that is something to ponder as it would be a precedent (re. user-visible linking strategies).