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

Document proc-macros despite bugs in rustdoc #491

Merged
merged 4 commits into from
Dec 6, 2019

Conversation

jyn514
Copy link
Member

@jyn514 jyn514 commented Nov 27, 2019

Use documentation in /target/doc if /target/$target/doc doesn't exist.
In that case, also don't pass --target to rustdoc.

Closes #422.

I also moved build_target into a separate function since build_package was getting kind of big.

r? @QuietMisdreavus

Use documentation in /target/doc if /target/$target/doc doesn't exist.

Partially addresses rust-lang#422.

Note: this does _not_ fix the issue mentioned above, it doesn't link
to the right CSS files. See
https://cdn.discordapp.com/attachments/541978667522195476/649031211913838592/unknown.png
for an example.
@QuietMisdreavus
Copy link
Member

Is there an issue on Cargo or rustdoc tracking the problem upstream?

I remember we talked about there sometimes being a problem with it not respecting --static-root-path. Does not passing --target on the "test build" solve that?

I also see that you don't build any extra targets for proc-macros. This gets around the immediate issue, but i can't shake the feeling that there's going to be a proc-macro somewhere that does something different per-platform. This might work for now, but we should really be reporting this to Cargo so that this can be fixed properly.

@jyn514
Copy link
Member Author

jyn514 commented Nov 27, 2019

Is there an issue on Cargo or rustdoc tracking the problem upstream?

Yes, rust-lang/rust#66796.

Does not passing --target on the "test build" solve that?

Yes.

there's going to be a proc-macro somewhere that does something different per-platform

Probably, and it might make sense come back to this once the upstream issue is fixed, but I think this hits the vast majority of use cases without being terribly hard to change in the future.

@jyn514
Copy link
Member Author

jyn514 commented Nov 27, 2019

Just for help reviewing - you can build an example proc macro with docker-compose run web build crate rstest 0.4.0, the compiled docs should look something like this:

image

Copy link
Member

@QuietMisdreavus QuietMisdreavus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should work for now as a stopgap solution. I want to ask the Cargo team about this issue, and see if it's intended behavior like it is for build scripts. In the meantime, this should allow proc-macro crates to actually display documentation. I'm not happy about not having anything in the "Platforms" menu, but that can possibly be fixed separately. For now, let's just get this in.

@QuietMisdreavus QuietMisdreavus merged commit aee309f into rust-lang:master Dec 6, 2019
@jyn514 jyn514 deleted the proc-macro-hack branch December 7, 2019 04:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Missing docs for procedural macro crate
2 participants