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

Adding rustdoc-args = ["--generate-link-to-definition"] in [package.metadata.docs.rs] makes documentation coverage dissapear #2581

Closed
carloskiki opened this issue Aug 8, 2024 · 10 comments · Fixed by rust-lang/rust#129050

Comments

@carloskiki
Copy link

carloskiki commented Aug 8, 2024

Its seems that all crates that are documented with the option rustdoc-args = ["--generate-link-to-definition"] do not have the "documentation coverage" section in the crates' drop down menu in docs.rs.

For example: clap, vs tokio

Why is that? Why can't there always be the coverage info displayed?

@syphar
Copy link
Member

syphar commented Aug 8, 2024

I'm not sure where the problem is here,

my hunch would be that the rustdoc command we generate for coverage can't handle this specific arg, but I need to sift through some logs to find the actual error.

( currently we skip over coverage and just build the docs in case of an error generating coverage)

@carloskiki
Copy link
Author

carloskiki commented Aug 9, 2024

Maybe its with the rustdoc-args parameter as a whole, because there is the --show-coverage argument which you can pass to rustdoc to have an overview of your docs coverage printed to stdout. I assume this argument is used to get the coverage for docs.rs, and it overlaps with crates providing their own set of rustdoc-args.

@syphar
Copy link
Member

syphar commented Aug 13, 2024

I needed to jump though some hoops to find the actual error message.

It is :

[stderr] error: --generate-link-to-definition option can only be used with HTML output format

@GuillaumeGomez do you have an idea how to solve this best?

in my mind, we probably need some of the rustdoc-args for coverage, but filtering would be hard.

Could rustdoc just ignore ( and warn) ?

@GuillaumeGomez
Copy link
Member

We could indeed emit a warning and mention that the option will be ignored.

@syphar
Copy link
Member

syphar commented Aug 13, 2024

We could indeed emit a warning and mention that the option will be ignored.

@GuillaumeGomez that would be awesome, thanks!

@GuillaumeGomez
Copy link
Member

Already opened rust-lang/rust#129050. :p

@syphar
Copy link
Member

syphar commented Aug 13, 2024

I wonder if we should collect & store the coverage logs too...

@GuillaumeGomez
Copy link
Member

I mean, that would have helped here.

GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Aug 13, 2024
…finition-warning, r=notriddle

Emit a warning instead of an error if `--generate-link-to-definition` is used with other output formats than HTML

Fixes rust-lang/docs.rs#2581.

It's a bit weird to emit an error in this case anyway, a warning is more than enough.

r? `@notriddle`
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Aug 13, 2024
…finition-warning, r=notriddle

Emit a warning instead of an error if `--generate-link-to-definition` is used with other output formats than HTML

Fixes rust-lang/docs.rs#2581.

It's a bit weird to emit an error in this case anyway, a warning is more than enough.

r? ``@notriddle``
rust-timer added a commit to rust-lang-ci/rust that referenced this issue Aug 14, 2024
Rollup merge of rust-lang#129050 - GuillaumeGomez:generate-link-to-definition-warning, r=notriddle

Emit a warning instead of an error if `--generate-link-to-definition` is used with other output formats than HTML

Fixes rust-lang/docs.rs#2581.

It's a bit weird to emit an error in this case anyway, a warning is more than enough.

r? ``@notriddle``
@GuillaumeGomez
Copy link
Member

rust-lang/rust#129050 is now merged, so tomorrow it should be fixed on docs.rs as well. Closing then.

@syphar
Copy link
Member

syphar commented Aug 15, 2024

Just validated that the change in nightly

  • is on docs.rs
  • is working

( I ran a rebuild for clap, and now we have coverage)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
3 participants