rustdoc edit links #2985

SOF3 · 2020-09-10T12:41:05Z

Adds an edit button to rustdoc-generated pages

text/0000-doc-edit-links.md

ehuss · 2020-09-16T21:35:31Z

Assuming this is intended for docs.rs to implement, how would it construct the URL? Is that something that would go in [package.metadata.docs.rs]?

SOF3 · 2020-09-17T02:19:58Z

The repository attribute in Cargo.toml already allows to specify the repository location. After that, docs.rs can perform a best-effort attempt that covers majority of use cases to detect the location of the path inside the repository:

Assume the default branch (this is the tree rendered by GitHub when linked from the docs.rs navbar anyway)
Search all instances of Cargo.toml
Find the Cargo.toml package with identical name as the published one
Construct {repository}/edit/{default_branch}/{package_path}/src/\{file\} as the path to pass into rustdoc

It would be great enhancement to be able to specify branch and package_path, but in general this is just a best-effort approach that usually works. There is nothing we can do about renamed files, and it would be costly to try to poll the git diff for actively updating line number offsets, however I suppose it won't hurt to add a link that mostly works and usually lands near the right line.

lebensterben · 2020-09-17T03:03:29Z

I agree that UI design is important especially for mobile devices.

I think it'd be better not to put an "edit" button beside the "src" button.
Instead, in the "src" page, there's already a ">" button on the left edge to open a file "drawer". We can put the "edit" button below or above that.

First, I think editing the documentation itself is more developer-oriented and is not something for every library users. So it can afford to be placed deeper in UI.

More importantly, I believe the editors must have at least looked at the source for the documentation, and probably at the source code itself, then they can make a rightful judgement on whether some documentation indeed needs modifications.

Lokathor · 2020-09-17T03:36:01Z

Yeah, reserving the edit button for when you're already looking at the source itself is much better.

SOF3 · 2020-09-17T03:51:22Z

What if the user is just trying to fix a typo or paraphrase the documentation to make it simpler?

Lokathor · 2020-09-17T03:59:04Z

Rustdoc already generates very busy pages that are full of too much cruft.

The common case is reading, so we should have the default view be oriented accordingly.

lebensterben · 2020-09-17T04:13:40Z

What if the user is just trying to fix a typo or paraphrase the documentation to make it simpler?

@SOF3 if someone is willing to spend time on making a PR to fix a typo, I believe he/she won't mind making an additional click.

SOF3 · 2020-09-17T04:22:43Z

Rustdoc already generates very busy pages that are full of too much cruft.

The common case is reading, so we should have the default view be oriented accordingly.

I was thinking like a ✏️ icon that appears when the user hovers over the [src] button

lebensterben · 2020-09-17T04:30:43Z

...

@SOF3 how do you hover on touch screen?

SOF3 · 2020-09-17T06:47:20Z

...

@SOF3 how do you hover on touch screen?

Press down your finger on the element, then drag it a bit to any direction so that it doesn't register as a click.

lebensterben · 2020-09-17T08:04:03Z

...

@SOF3 how do you hover on touch screen?

Press down your finger on the element, then drag it a bit to any direction so that it doesn't register as a click.

that won't work on ios

jyn514 · 2020-09-18T15:18:14Z

Related to rust-lang/rust#74758 - could there be two different views of the page? One that's intended for viewing and one for editing? Then the editing one would show much less detail, but would also have the ✏️ button.

jyn514

I really like the idea, but this RFC proposes a goal, not a way how to get there. Consider posting this as a pre-rfc on https://internals.rust-lang.org/ to get more ideas on the design - as-is, this isn't really actionable for the rustdoc team.

jyn514 · 2020-09-20T12:50:38Z

text/0000-doc-edit-links.md

+```
+--edit-link-format "https://github.com/rust-lang/rust/edit/master/libstd/{file}#L{start_line}-L{end_line}"
+```
+


This is missing a reference-level explanation. Consider addressing what the UI would look like for this.

jyn514 · 2020-09-20T12:51:50Z

text/0000-doc-edit-links.md

+[drawbacks]: #drawbacks
+
+This increases complexity of the documentation page, especially with mobile devices.
+Good UX design is required to prevent bloating the content.


This should really be part of the RFC, not deferred until later. Certainly no one on the rustdoc team has the bandwidth to design it.

jyn514 · 2020-09-20T12:56:47Z

text/0000-doc-edit-links.md

+
+Pros:
+
+- *May* support previous crate builds


It would be good to expand on why this is 'May'. The difficulty I forsee is changes in HTML page structure, but since the links always say '[src]' that could be mitigated somewhat. It highly depends where the buttons end up going, which is one more reason I think the design should be part of the RFC.

jyn514 · 2020-09-20T12:57:33Z

text/0000-doc-edit-links.md

+# Alternatives
+[alternatives]: #alternatives
+
+It is also possible to perform this with JavaScript on behalf of docs.rs only.


It wouldn't have to be with JavaScript, docs.rs already rewrites pages on the backend: https://github.com/rust-lang/docs.rs/blob/master/src/utils/html.rs

text/0000-doc-edit-links.md

jyn514 · 2020-09-20T13:04:36Z

Construct {repository}/edit/{default_branch}/{package_path}/src/{file} as the path to pass into rustdoc

I don't like this approach, it breaks for gitlab. What docs.rs could do instead is have a list of supported git hosts (that's fairly easy to add to) and choose the file path based on that and the repository field. +1 to not having more docs.rs specific data though.

Co-authored-by: Joshua Nelson <[email protected]>

jyn514 · 2020-09-21T15:20:14Z

text/0000-doc-edit-links.md

+
+This increases complexity of the documentation page, especially with mobile devices.
+Good UX design is required to prevent bloating the content.
+


This RFC will only show the links on new docs.rs pages, not existing builds. Can you add that as a drawback?

Co-authored-by: Joshua Nelson <[email protected]>

rustdoc edit links

524e264

jonas-schievink reviewed Sep 15, 2020

View reviewed changes

text/0000-doc-edit-links.md Outdated Show resolved Hide resolved

SOF3 added 2 commits September 15, 2020 22:26

Removed obsolete line

78b56a3

Removed empty reference-level explanation section

49acb5b

ehuss added the T-rustdoc Relevant to rustdoc team, which will review and decide on the RFC. label Sep 17, 2020

jyn514 suggested changes Sep 20, 2020

View reviewed changes

Update text/0000-doc-edit-links.md

c6fec7c

Co-authored-by: Joshua Nelson <[email protected]>

jyn514 reviewed Sep 21, 2020

View reviewed changes

Update text/0000-doc-edit-links.md

84c31ad

Co-authored-by: Joshua Nelson <[email protected]>


		This increases complexity of the documentation page, especially with mobile devices.
		Good UX design is required to prevent bloating the content.

rustdoc edit links #2985

Are you sure you want to change the base?

rustdoc edit links #2985

Uh oh!

Conversation

SOF3 commented Sep 10, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ehuss commented Sep 16, 2020

Uh oh!

SOF3 commented Sep 17, 2020

Uh oh!

lebensterben commented Sep 17, 2020

Uh oh!

Lokathor commented Sep 17, 2020

Uh oh!

SOF3 commented Sep 17, 2020

Uh oh!

Lokathor commented Sep 17, 2020

Uh oh!

lebensterben commented Sep 17, 2020

Uh oh!

SOF3 commented Sep 17, 2020

Uh oh!

lebensterben commented Sep 17, 2020

Uh oh!

SOF3 commented Sep 17, 2020

Uh oh!

lebensterben commented Sep 17, 2020

Uh oh!

jyn514 commented Sep 18, 2020

Uh oh!

jyn514 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jyn514 Sep 20, 2020

Choose a reason for hiding this comment

Uh oh!

jyn514 Sep 20, 2020

Choose a reason for hiding this comment

Uh oh!

jyn514 Sep 20, 2020

Choose a reason for hiding this comment

Uh oh!

jyn514 Sep 20, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jyn514 commented Sep 20, 2020

Uh oh!

jyn514 Sep 21, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

SOF3 commented Sep 10, 2020 •

edited

Loading

jyn514 left a comment •

edited

Loading