Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add line numbers for dead links #14

Open
stanislav-tkach opened this issue Oct 13, 2017 · 8 comments
Open

Add line numbers for dead links #14

stanislav-tkach opened this issue Oct 13, 2017 · 8 comments
Labels
C-enhancement Category: This is a new feature S-blocked Status: Blocked on another project

Comments

@stanislav-tkach
Copy link
Contributor

Sometimes it isn't trivial to find where dead link is actually located. I have to modify cargo-deadlinks locally with additional debug! print in order to find it. 😅 It would be nice to provide additional information.

@hobofan
Copy link
Member

hobofan commented Oct 13, 2017

Agree, would be a great future to have!

However with the current approach of analyzing the HTML output it's not really trivial to introduce.

AFAIK the solution with the best UX would very likely require nightly and involve a compiler plugin.


Compiler plugin variant (requires nightly)
  • Inject some kind of marker into every link (e.g. a UUID anchor tag) via a compiler plugin
  • The compiler plugin can then build a lookup table of UUID->position. The position can be determined via rust-docstrings; see also ronat where I've done something similar
  • When we find a broken link we can then get the code location from the lookup table
Stable variant - requires manual intervention and only works with comment-block granularity
  • Manually place a marker into the documentation like <!--- deadlinks-id: 123 --->
  • Since those comments stay in the generated output we can then find the appropriate comment block via ripgrep or similar

I'm open to other approaches. I wouldn't be surprised if there were some Markdown feature I'm missing we could (ab)use for this.

@hobofan hobofan added the C-enhancement Category: This is a new feature label Oct 13, 2017
@hobofan
Copy link
Member

hobofan commented Oct 13, 2017

Duplicate of #3, but this one stays since the other one has old information and I've written more here 😅

@hobofan
Copy link
Member

hobofan commented Oct 13, 2017

@DarkEld3r Having to modify cargo-deadlinks also shouldn't be necessary right now. What exactly are you logging that helps you pinpoint the issue?

Have you tried using the --verbose and --debug flags? That should usually give you a rough starting point.

@stanislav-tkach
Copy link
Contributor Author

Now I see, that I missed (info!) logging in the parse_html_file function. 😅 That will be enough for me.

@hobofan
Copy link
Member

hobofan commented Feb 19, 2018

rust-lang/rust#47046 recently landed which should combat the problem cargo-deadlinks was built for to some degree.

If we were to have this feature here implemented, we could probably also lint for the style in which a link was specified, and point people towards the new syntax of specifying links (maybe this should also be done in rustdoc directly).

@Marwes
Copy link
Contributor

Marwes commented Mar 21, 2019

Just printing the html file where the dead link was found would be nice. That would narrow the search down a lot and is useful for non-rustdoc .html as well.

@jyn514
Copy link
Contributor

jyn514 commented Oct 17, 2020

Just printing the html file where the dead link was found would be nice. That would narrow the search down a lot and is useful for non-rustdoc .html as well.

The output now looks like this:

Found invalid urls in /home/joshua/.local/lib/cargo/target/doc/toggle/struct.Args.html:
	Linked file at path /home/joshua/.local/lib/cargo/target/doc/structopt/trait.StructOptInternal.html does not exist!
	Linked file at path /home/joshua/.local/lib/cargo/target/doc/structopt/trait.StructOptInternal.html does not exist!
	Linked file at path /home/joshua/.local/lib/cargo/target/doc/structopt/trait.StructOptInternal.html does not exist!
	Linked file at path /home/joshua/.local/lib/cargo/target/doc/structopt/trait.StructOptInternal.html does not exist!

Is that clear enough to find what went wrong, or would you like it to be more specific? Tracing that back to the source file will be very hard like hobofan said, but adding a line number should be pretty easy.

@Marwes
Copy link
Contributor

Marwes commented Oct 17, 2020

Yeah, as long as I have the link it is easy to find where it comes from (though having the line directly ould of course be better)

@jyn514 jyn514 changed the title Print location of the dead links Add line numbers for dead links Oct 18, 2020
@jyn514 jyn514 added this to the 0.5.0 milestone Oct 18, 2020
@jyn514 jyn514 added the S-blocked Status: Blocked on another project label Nov 18, 2020
@jyn514 jyn514 mentioned this issue Nov 19, 2020
4 tasks
@jyn514 jyn514 removed this from the 0.5.0 milestone Nov 19, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-enhancement Category: This is a new feature S-blocked Status: Blocked on another project
Projects
None yet
Development

No branches or pull requests

4 participants