-
Notifications
You must be signed in to change notification settings - Fork 120
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
Automating screenshots for documentation #501
Comments
I wonder if that should also include snapshot testing? We could use the git commit versioned link I think like this: https://media.githubusercontent.com/media/linebender/vello/5aa5937d78dd1ec3b5b067dc173781858c38550e/vello_tests/snapshots/splash.png (after a quick skim of the response headers, I think it should work embedded in docs.rs). So when a screenshot changes, "breaking" the (doc-)tests, then a local link to the screenshot has to be made to resolve the issue in CI. But it would at least make sure that all the screenshots are up to date and valid with the current (or following) commit. |
I don't understand what you're asking here. Wouldn't these screenshots already be snapshot tested? I'm hesitant to use those Git commit URLs, for three reasons:
|
I meant commits based on main, i.e. have a local link to that file (something like
Ah yeah, that would include the snapshots, I think I've thought about some kind of doc-comment-tests, producing a screenshot, which would directly serve as snapshot-test |
My current plan is to not even bother creating a "book"-type documentation page, and just have all our documentation in rustdoc format, including tutorials. See #632 for what that looks like. The upside of doing that is we might not need any additional CI. I'm not sure this lets us use local file paths, though, unless whatever |
Overall, that sounds like a good plan, but I struggle to see how that follows. Is this thread not discussing workarounds to let us have images in rustdoc? There are two related root causes for this issue existing, which I perhaps didn't lay out clearly enough, but which are discussed in the linked rustdoc issue:
Additionally, docs.rs doesn't work based on the repositories, instead it works based on the uploaded crate. That allows it to work for any crate, not just those which happen to have a public repository. |
Oh, I see. Yeah, in that case, I have nothing. |
I've given it some thought, and I have a potential solution: We do something similar to #663 Basically, we write an That way, |
Quick check suggests the only way to get the current commit hash is from a |
That's one direction we can explore. I don't know how diligent we are with tags, but if we do already use them, it's fine. As far as I know |
Our documentation currently does not include screenshots, which can be instrumental in understanding the purpose of different widgets.
Since #475 (which landed as part of #233), we are able to store screenshots in this repository. We should find a way to include some of these screenshots in our documentation. For example, see
TextInput
iniced
.Ideally, this would be natively supported by rustdoc. This is tracked in rust-lang/rust#32104
However, we would like to have something working before this is resolved, as that issue has been open for a very long time.
The implementation pathway I would recommend is to host a GitHub pages site from a folder in this repository (https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow). We would then use URLs to this site in our documentation.
I do foresee some concerns with this approach:
However, this approach would still be a significant improvement from our current state.
The text was updated successfully, but these errors were encountered: