Docs.rs: Missing docs for procedural macro crate

[la10736]

I noted this behavior yesterday (2019/10/3). After published last version of a crate of mine (rstest) I took a look to crate.io to check everything.

Doc link exists https://docs.rs/crate/rstest/0.4.0 but just page is marked as _not a library_ and _Doc_ tab is missed.

I took a look to other procedural macro crates published in the last days and all have the same issue.

I missed something?

Thanks

[pietroalbini]

This is a bug in docs.rs, working on a fix.

[pietroalbini]

That patch didn't fix it, investigating a bit more.

[la10736]

Something seams changed now: Now _not a library_ message is replaced bi _doesn't have any documentation_.
Maybe should I just push a new version to trigger doc publication for the new version?

[QuietMisdreavus]

No, that will still happen. The bug is that cargo will always emit docs for proc-macro crates into target/doc, even if a --target flag was provided. (Usually, they'd go into target/$target/doc instead.) I'm working on a proper fix for it, but i'm running into other issues on my test server, so it's slow going.

[la10736]

@QuietMisdreavus Ok... fine and thanks!

[glts]

Are there workarounds for this bug? No proc macro docs can currently be published, right?

[Arnavion]

Leaving bugs like this unfixed for a month gives a bad look to docs.rs. Is it possible for you to roll back to the previous toolchain that you used which didn't have this issue?

(Yes I know it's a free service, and if I don't like it I can host the docs myself. I'm not complaining.)

[pietroalbini]

Is it possible for you to roll back to the previous toolchain that you used which didn't have this issue?

No, the old build environment is not present on the server anymore. Even if the it was still present we wouldn't roll back to it, as it lacked many sandboxing features introduced in the new one.

[Arnavion]

So the issue is with the new build environment, not a toolchain update? Does that mean the new environment was not tested with (at least) proc macro crates before it was deployed?

[pietroalbini]

So the issue is with the new build environment, not a toolchain update?

Yep. The new build environment exposed a Cargo bug (https://github.com/rust-lang/docs.rs/issues/422#issuecomment-545558741), and I'm not sure whether @QuietMisdreavus wants to work around it on docs.rs itself first or fix it upstream directly.

Does that mean the new environment was not tested with (at least) proc macro crates before it was deployed?

Unfortunately we forgot to test with proc macro crates before deploying, yes :(

[Arnavion]

Okay, thank you. I hope docs WG can establish a release process so that it doesn't happen again :)

[la10736]

No, that will still happen. The bug is that cargo will always emit docs for proc-macro crates into target/doc, even if a --target flag was provided. (Usually, they'd go into target/$target/doc instead.) I'm working on a proper fix for it, but i'm running into other issues on my test server, so it's slow going.

@QuietMisdreavus I wasn't able to find the ticket in cargo repo. I would like to try to help on it because this issue is blocking for lot of procedural macro crate: Who know this issue wait on this fix to publish his crate, but who don't know just give the feels to his peers that he doesn't care about documentations: that's just sad.

If the fix of this issue is far away to come we should find some kind of workaround to it. A message that link this issue to the page where the docs is missing should be the minimal bit to alleviate the problem.

[GuyL99]

My crate metropolis seems to have a similar problem as well:
https://crates.io/crates/metropolis
Do you know to if it's the same problem?
And if it is was anyone able to figure out a solution(or a hack)?

[la10736]

@GuyL99 My guess is no... your crate isn't a procedural macro crate (this issue is just about procedural macro crates).

Maybe you hit some limits or try to access to external resource: take a look to https://docs.rs/about

[jyn514]

@QuietMisdreavus do you know if there's an issue open for rustdoc about this? If not I can open one.

Separately, could we work around this in the meantime by looking in target/doc if target/$target/doc is empty?

[jyn514]

Relevant code: https://github.com/rust-lang/docs.rs/blob/master/src/docbuilder/rustwide_builder.rs#L284

[davidpdrsn]

I’m currently hitting this bug with my crate bae. Is there any possible workaround?

[jyn514]

@davidpdrsn not for proc-macro authors, no. I have a work-around on our end in https://github.com/rust-lang/docs.rs/pull/491, but @QuietMisdreavus wants to fix the upstream bug (https://github.com/rust-lang/rust/issues/66796) first.

[jyn514]

For everyone who's been impacted: This has been fixed but the fix has not yet been deployed. Once it has (hopefully sometime next week), I'll comment again and you can publish your docs by publishing a new patch version of your crate.

[pietroalbini]

This has been deployed! Rebuilt rstest and bae. If other crates need to be rebuilt feel free to comment here.

[jyn514]

@pietroalbini can you also rebuild tokio-macros 0.2.0?

cc @pickfire , https://github.com/rust-lang/docs.rs/issues/420#issuecomment-562869349

[pietroalbini]

Queued tokio-macros 0.2.0.

[CreepySkeleton]

Could you please also rebuild getset 0.0.9?

[pietroalbini]

Queued.

[CreepySkeleton]

Would it be possible to rebuild derive_builder 0.8.0, 0.8.1, and 0.9.0?

[jyn514]

@CreepySkeleton queued and rebuilt! https://docs.rs/derive_builder/0.9.0/derive_builder/

[theypsilon]

Could you please rebuild arraygen 0.1.12?

[jyn514]

@theypsilon arraygen succeded the first time it was built, there's no need to build it again: https://docs.rs/arraygen/0.1.12/arraygen/

[theypsilon]

@theypsilon arraygen succeded the first time it was built, there's no need to build it again: https://docs.rs/arraygen/0.1.12/arraygen/

It didn't generate all the doc blocks though: https://github.com/theypsilon/arraygen/blob/master/src/lib.rs

It was one of the first days after it started generating docs again, so maybe there was a problem at that time.

[jyn514]

This doesn't sound related the bug in this issue. Can you open a new issue with more details?