Closed Enyium closed 4 months ago
Great idea. Those pages are automatically generated via rustdoc so I think we'd need to keep manually patching the output to reference OpenSearch XML. I'll take a closer look though.
I recommend creating an issue at https://github.com/rust-lang/rust/issues/ about getting this added to rustdoc itself. Closing this issue for now as there's nothing to do here (for the crate itself). Feel free to keep the discussion going though!
rustdoc
has --html-in-header
! That wouldn't be hacky patching.
I don't think rustdoc
would be changed to always include the OpenSearch stuff. And if it would be a more semantic, dedicated OpenSearch-related switch, it wouldn't make much of a difference towards the --html-in-header
solution.
@riverar: Would you please consider reopening the issue, since you made the incorrect assumption that rustdoc
would need to change something to support this, while it already does support it?
Sure, thanks for the ping.
I'm not convinced this has anything to do with windows-rs and that Windows crates should support this if it's not applicable to Rust crates generally. There should at least be a discussion with the rustdoc folks about this at the very least before anything happens in the windows-rs project.
@Enyium I added this to the latest deployment of https://microsoft.github.io/windows-docs-rs/doc/windows/ but not sure how to test it. Also suspect this will never work with the sub-domain/folder hierarchy we have.
@riverar:
It works well! I now have the search function "Rust for Windows".
The only strange things are these:
There's a problem with your .xml file that could perhaps be the cause of some problems. Here, it says about the title
attribute of the <link>
element: "must match your plugin file's <ShortName>
". But you used different strings.
Maybe for the icon you could use the four-colored Windows logo without white bars and use the Rust logo as a mask to give the colors the Rust logo shape. Then maybe add a thin black border around the shape. Or, if you can't be bothered with this complexity, add the Windows logo to the Rust logo like a small shortcut overlay is added to .lnk file icons under Windows.
@kennykerr:
Why should you have to talk to the rustdoc folks when they offer CLI switches to change the HTML according to your demands yourself?
I don't view the windows-Crate as just another crate, since it may be used across projects, not simply something you need for a certain project, and requires considerably more looking up of things. But, granted, you could argue that there are also other very basic crates like tokio
, and you might like a search function for that, if you're repeatedly needing to search it. But, in my understanding, the people to contact for that would not be the rustdoc folks, but the docs.rs folks that have automated pipelines using rustdoc. However, what's an icon-identified search function without a distinguishing icon? And crates don't come with icons.
@Enyium Good catch on the xml, will fix that. Can you provide some test steps so I can test locally? I tried using the URL in Chrome, Edge, and Firefox and nothing happened--perhaps I have something locked down?
This is what I found out:
In Firefox Developer Edition, I have my layout arranged so that I have a dedicated search textbox to the right of the address bar. There, I can easily acccept the offer. But when clicking on the address bar text, this is also possible with the flyout box that appears (via the icon bar at the bottom).
If you want to check another functioning OpenSearch engine, github.com has one.
I made some tweaks to the latest OpenSearch XML but seems like OpenSearch is very dead and barely works even in Mozilla Firefox. Going to close this for now as it's not worth investing much more time into this.
Suggestion
OpenSearch description format: https://developer.mozilla.org/en-US/docs/Web/OpenSearch
By adding an XML file to your HTML and server, people will be offered to add a search function in their browsers that searches with a URL like
https://microsoft.github.io/windows-docs-rs/doc/windows/?search={searchTerms}
. Then you wouldn't need a bookmark, which is more cumbersome to utilize.