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

Remove syn dependency by relying only on doc = embed_image! functionality. #1

Open
Andlon opened this issue Feb 16, 2022 · 5 comments

Comments

@Andlon
Copy link
Owner

Andlon commented Feb 16, 2022

Currently, syn is only necessary for the embed_doc_image attribute. Although the #[embed_doc_image] also works on older Rust versions, it seems like a reasonable trade-off to only be able to generate docs for Rust > 1.54. Then we can remove #[embed_doc_image] as well as syn. The remaining dependencies are hopefully lightweight enough that most users won't need to disable them during non-doc compilation.

We should also simplify documentation to focus on the case when Rust >= 1.54 - in which case using embed-doc-image is easy, and put less emphasis on all the workarounds for making code compile on Rust < 1.54 (although still discuss them).

Additionally, as suggested by @GuillaumeGomez here, we can use cfg(doc) to ensure that embed_image! evaluates to a no-op when not compiling docs.

Finally, we should also provide an enabled feature that, when not enabled, makes the whole crate a no-op with no dependencies. This way it's possible for users to only embed doc images when a feature, and otherwise pay no price whatsoever when the feature is not enabled.

@GuillaumeGomez
Copy link

GuillaumeGomez commented Feb 16, 2022

I'd also add that it could be much simplified if this cargo issue was fixed to allow to have dependencies only doc build.

@Andlon
Copy link
Owner Author

Andlon commented Feb 16, 2022

It was just pointed out to me in the community Discord that #[cfg(doc)] interacts poorly with dependencies. My understanding is that this configuration directive is not necessarily applied to dependencies. The result of this in the context of this crate could be that images are not embedded in dependencies, which seems unfortunate.

This suggests that using cfg(doc) unfortunately is off the table...

@GuillaumeGomez
Copy link

I'm a bit surprised. Do you have an example where cfg(doc) isn't working nicely? (that might allow to fix things in rustdoc directly)

@Andlon
Copy link
Owner Author

Andlon commented Feb 16, 2022

@GuillaumeGomez: I'm just going by the word of @Nemo157 here, to be honest. I don't have an explicit example myself, unfortunately.

@GuillaumeGomez
Copy link

Ah right, cfg(doc) isn't propagated to dependencies, which is an issue...

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

No branches or pull requests

2 participants