rustdoc: redirect URLs #35236

nrc · 2016-08-03T01:55:07Z

cc #35020 which does this properly

nrc · 2016-08-03T22:09:23Z

alexcrichton · 2016-08-04T17:13:50Z

@nrc so just to clarify, this emits Foo.v.html which redirects to struct.Foo.html?

ollie27 · 2016-08-04T17:26:18Z

As with the previous PR, methods and struct fields are in the same namespace so we get conflicts. For example std::ops::Range has two start.v ids. Is that not a problem?

nrc · 2016-08-04T21:06:00Z

As with the previous PR, methods and struct fields are in the same namespace so we get conflicts. For example std::ops::Range has two start.v ids. Is that not a problem?

It is, but without changing the canonical URLs/anchors there doesn't seem to be a great way to disambiguate. However, since these are not canonical URLs, it doesn't really matter - for tool users who link to Rustdoc, there will be a very few URLs that don't work properly, but I expect this to be a pretty small edge case.

nrc · 2016-08-04T21:07:01Z

so just to clarify, this emits Foo.v.html which redirects to struct.Foo.html?

Well, Foo.t.html, but yes that is basically what is happening here, plus the extra anchors for 'sub-items'.

alexcrichton · 2016-08-08T16:56:45Z

@bors: r+ 525b77e

ollie27 · 2016-08-08T18:22:50Z

There are a few issues with the implementation:

Nested <a> tags are invalid so you'll need to use another tag for the new ids.
ids are supposed to be unique so you'll need to call derive_id for all the new ones.
There should probably be a few new tests 😉.

alexcrichton · 2016-08-08T18:26:34Z

@bors: r-, ah, good points!

bors · 2016-08-09T01:55:20Z

⌛ Testing commit 525b77e with merge 8d86593...

alexcrichton · 2016-08-09T02:04:32Z

@bors: r-

er... maybe a mis-parse?

bors · 2016-08-09T03:52:14Z

💔 Test failed - auto-win-msvc-64-opt-rustbuild

nrc · 2016-08-09T04:31:07Z

bors is clearly hungry for this PR, it won't take 'no' for an answer

nrc · 2016-08-11T23:53:00Z

re tests, does anyone (@ollie27?) have suggestions for how to test the existence of the redirects? I don't see a way to fit it into the existing framework, but I don't know it very well.

alexcrichton · 2016-08-12T18:33:29Z

I think you can at least test for their existence with the rustdoc tests, and maybe html tags inside them as well?

ollie27 · 2016-08-14T15:25:49Z

Check out test/rustdoc/redirect.rs and test/rustdoc/issue-33302.rs for examples which test the same kind of things.

For example I'd do something like the following for structs:

#![crate_name = "foo"]

// @has 'foo/FooStruct.t.html'
// @has - '//p/a' 'struct.FooStruct.html'
// @has 'foo/struct.FooStruct.html'
pub struct FooStruct {
    // @has - '//*[@id="foo.v"]' 'foo'
    pub foo: (),
    // @has - '//*[@id="dupe.v"]' 'dupe'
    pub dupe: (),
}
impl FooStruct {
    // @has - '//*[@id="bar.v"]' 'bar'
    pub fn bar() {}
    // @has - '//*[@id="dupe.v-1"]' 'dupe'
    pub fn dupe() {}
}

You should be able repeat that for every other item type.

nrc · 2016-08-14T22:53:21Z

@ollie27 I tried something like this and it doesn't work. I'm not really clear on the semantics of @has, but I'm assuming it is ensuring that the text string occurs in the generated document. So, your example is saying that there should be a link to each of struct.FooStruct.html and FooStruct.t.html, which there isn't - there is only a link to the former. Is my understanding correct? Is there a way to check for the existence of a file?

ollie27 · 2016-08-15T11:44:12Z

Check out src/etc/htmldocck.py for a better explanation than I could give.

nrc · 2016-08-15T20:03:22Z

Thanks for the link, I knew these must be documented somewhere.

PATH is relative to the output directory. It can be given as - which repeats the most recently used PATH.

This is what was tripping me up.

nrc · 2016-08-15T22:23:26Z

Updated with tests, spans instead of anchors, and unique ids.

@alexcrichton r?

alexcrichton · 2016-08-16T00:29:50Z

@bors: r+ 6765f7e

bors · 2016-08-16T11:41:28Z

⌛ Testing commit 6765f7e with merge 30adf96...

bors · 2016-08-16T13:22:14Z

💔 Test failed - auto-win-gnu-32-opt-rustbuild

ollie27 · 2016-08-16T14:14:49Z

src/librustdoc/html/render.rs

-                           </span><span class='stab {stab}'></span>",
-                       shortty = ItemType::StructField,
+                write!(w, "<span id='{item_type}.{name}' class='{item_type}'>
+                           <span id='{name}.{name_space}' class='invisible'>


You'll need to use derive_id for these as well. The existing ids are also missing a call to derive_id so you may as well also fix that while you're at it.

ollie27 · 2016-08-16T14:14:53Z

src/librustdoc/html/render.rs

@@ -2366,9 +2389,12 @@ fn item_enum(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
                    if let StructFieldItem(ref ty) = field.inner {
                        write!(w, "<tr><td \
                                   id='variant.{v}.field.{f}'>\
-                                   <code>{f}:&nbsp;{t}</code></td><td>",
+                                   <span id='{v}.{vns}.{f}.{fns}' class='invisible'>\


ollie27 · 2016-08-16T14:18:11Z

I was hoping you'd add a new test covering every single item type. For example enum variant struct fields and macros are different so need explicit tests.

Are you going to document this feature anywhere? What kind of stability guarantees do these new URLs have? Can other people use them?

nrc · 2016-08-16T20:47:19Z

I was hoping you'd add a new test covering every single item type. For example enum variant struct fields and macros are different so need explicit tests.

I suppose a few more tests couldn't hurt. The main code paths are exercised and the coverage seems as good or better than existing Rustdoc tests.

Are you going to document this feature anywhere?

No. I see no point in encouraging use of these until the long-term URL solution is figured out.

What kind of stability guarantees do these new URLs have?

None, use at your own risk.

Can other people use them?

Sure, but I wouldn't encourage it.

You'll need to use derive_id for these as well. The existing ids are also missing a call to derive_id so you may as well also fix that while you're at it.

I was assuming there was some logic behind not calling derive_id here (e.g., you can't have duplicate named fields, so I assume there can't be a name clash).

ollie27 · 2016-08-16T21:30:26Z

The main code paths are exercised and the coverage seems as good or better than existing Rustdoc tests.

The test coverage in rustdoc isn't very good right now so we should be aiming for better coverage.

I was assuming there was some logic behind not calling derive_id here (e.g., you can't have duplicate named fields, so I assume there can't be a name clash).

derive_id is also used by the markdown so I was worried it might conflict there but having a closer look, it turns out the markdown will never create an id containing a . so technically they can't conflict. It wouldn't harm to call derive_id though, we definitely need to call it for the new ones anyway.

pulled out of rust-lang#35020

… ones cc rust-lang#35020 which does this properly

nrc · 2016-08-17T04:08:11Z

@bors r=@alexcrichton

bors · 2016-08-17T04:08:12Z

📌 Commit 879637f has been approved by @alexcrichton

bors · 2016-08-17T10:20:13Z

⌛ Testing commit 879637f with merge 6c0d66a...

@alexcrichton

rustdoc: redirect URLs cc #35020 which does this properly r? @alexcrichton

bors · 2016-08-17T13:25:53Z

nrc added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Aug 3, 2016

rust-highfive assigned alexcrichton Aug 3, 2016

nrc mentioned this pull request Aug 3, 2016

rustdoc: simplify URLs #35020

Closed

nrc force-pushed the rustdoc-redirects branch from b123806 to 525b77e Compare August 3, 2016 22:08

ollie27 reviewed Aug 16, 2016
View reviewed changes

nrc added 3 commits August 17, 2016 10:30

rustdoc: refactoring and tidying up

7a7cd64

pulled out of rust-lang#35020

rustdoc: add namespaces for items

a41454b

rustdoc: redirects from sane, namespaced URLs to Rustdoc's ridiculous…

77ca7dd

… ones cc rust-lang#35020 which does this properly

nrc force-pushed the rustdoc-redirects branch from 6765f7e to 879637f Compare August 17, 2016 04:07

Review changes

879637f

bors added a commit that referenced this pull request Aug 17, 2016

Auto merge of #35236 - nrc:rustdoc-redirects, r=@alexcrichton

6c0d66a

rustdoc: redirect URLs cc #35020 which does this properly r? @alexcrichton

bors mentioned this pull request Aug 17, 2016

Rollup of 23 pull requests #35747

Merged

bors merged commit 879637f into rust-lang:master Aug 17, 2016

This was referenced Aug 17, 2016

Center content of the generated docs #35682

Closed

rustdoc: remove the ! from macro URLs and titles #35234

Merged

jonas-schievink mentioned this pull request Oct 15, 2016

rustdoc for liblibc is 2.3GB large #37183

Closed

steveklabnik mentioned this pull request Dec 22, 2016

Simplify rustdoc URLs #34271

Closed

ollie27 mentioned this pull request Dec 6, 2018

[rustdoc] Remove old style files #56577

Closed

ollie27 mentioned this pull request Jun 29, 2020

[rustdoc] Page hash handling #70563

Merged

jyn514 mentioned this pull request Aug 26, 2020

Use name.namespace.html as the canonical URL, not kind.name.html #55160

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rustdoc: redirect URLs #35236

rustdoc: redirect URLs #35236

nrc commented Aug 3, 2016

nrc commented Aug 3, 2016

alexcrichton commented Aug 4, 2016

ollie27 commented Aug 4, 2016

nrc commented Aug 4, 2016

nrc commented Aug 4, 2016

alexcrichton commented Aug 8, 2016

ollie27 commented Aug 8, 2016

alexcrichton commented Aug 8, 2016

bors commented Aug 9, 2016

alexcrichton commented Aug 9, 2016

bors commented Aug 9, 2016

nrc commented Aug 9, 2016

nrc commented Aug 11, 2016

alexcrichton commented Aug 12, 2016

ollie27 commented Aug 14, 2016

nrc commented Aug 14, 2016

ollie27 commented Aug 15, 2016

nrc commented Aug 15, 2016

nrc commented Aug 15, 2016

alexcrichton commented Aug 16, 2016

bors commented Aug 16, 2016

bors commented Aug 16, 2016

ollie27 Aug 16, 2016

ollie27 Aug 16, 2016

ollie27 commented Aug 16, 2016

nrc commented Aug 16, 2016

ollie27 commented Aug 16, 2016

nrc commented Aug 17, 2016

bors commented Aug 17, 2016

bors commented Aug 17, 2016

bors commented Aug 17, 2016

rustdoc: redirect URLs #35236

rustdoc: redirect URLs #35236

Conversation

nrc commented Aug 3, 2016

nrc commented Aug 3, 2016

alexcrichton commented Aug 4, 2016

ollie27 commented Aug 4, 2016

nrc commented Aug 4, 2016

nrc commented Aug 4, 2016

alexcrichton commented Aug 8, 2016

ollie27 commented Aug 8, 2016

alexcrichton commented Aug 8, 2016

bors commented Aug 9, 2016

alexcrichton commented Aug 9, 2016

bors commented Aug 9, 2016

nrc commented Aug 9, 2016

nrc commented Aug 11, 2016

alexcrichton commented Aug 12, 2016

ollie27 commented Aug 14, 2016

nrc commented Aug 14, 2016

ollie27 commented Aug 15, 2016

nrc commented Aug 15, 2016

nrc commented Aug 15, 2016

alexcrichton commented Aug 16, 2016

bors commented Aug 16, 2016

bors commented Aug 16, 2016

ollie27 Aug 16, 2016

Choose a reason for hiding this comment

ollie27 Aug 16, 2016

Choose a reason for hiding this comment

ollie27 commented Aug 16, 2016

nrc commented Aug 16, 2016

ollie27 commented Aug 16, 2016

nrc commented Aug 17, 2016

bors commented Aug 17, 2016

bors commented Aug 17, 2016

bors commented Aug 17, 2016