I personally find MDN docs skinning more enjoyable than RustDoc. I've said something similiar about JavaDoc too, as well. Anyone feels something similiar? I think it needs to change. Currently I can't achieve anything because RustDoc only allows to customize CSS.
For comparison:
ffmpeg_next::Chapter
RegExp
P.S.: regarding user experience, RustDoc is pretty well-accessible. I'm just pointing that I don't find it visually pleasant.
Interestingly, at least in the part of the Rust world I'm exposed to on Twitter, most people weren't very fond of the early 2022 MDN redesign.
Rustdoc offers a JSON output of its collected data. If you want an alternative frontend, rendering from that is going to be the way forward.
Structurally different frontend skins essentially aren't going to ever be supported by Rustdoc. Rustdoc has the interesting constraint of needing to be an entirely static site browsable straight off of the filesystem and not requiring any JavaScript to view the content of the page. Additionally, the team's already mildly concerned with the size of the rendered documentation bundle's size, and as such large increases to bundle size typically aren't accepted, especially if they wouldn't have any tangible benefit to the average stable user.
In general, the team agrees that Rustdoc isn't a great solution of exploratory discovery of an API's functionality. However, improvements to Rustdoc's use as such aren't typically going to be accepted if they regress the primary goal of Rustdoc as reference documentation, or the secondary properties of static bundle size and JS-independence.
Oh, but I mean, that constraint won't be broken by changing the "skin" of the generated docs. It's just skin; functionality such as portability remains the same.
Are you sure they think so? Sometimes you just don't want to open an IDE and want to explore what a crate looks like before downloading it.
The problem is that while the information presented does stay the same, the structure of the presentation does change, and that's somewhere between very difficult and impossible to do with just switching out CSS. As much as semantic HTML is an ideal, HTML is a document language, and it describes the structure of the document, not the structure of the data. If you change the structure of the document, the HTML usually has to change to reflect that.
I'm not saying that they don't care about rustdoc usage as exploratory documentation, just that it's not the primary (but is still a) priority of the docs. What I'm trying to say there is that they know that it's suboptimal and would like to improve its functionality in that domain, just not at the (perceived?) expense of another priority of the system.
No need for reflecting changes in all existing docs in docs.rs. Just apply the new skin to future docs.rs docs.
So ... just dropping the current theme? Yeah, that's not going to happen.
@CAD97 already laid out some arguments and gave you information so you can work on alternative frontends: use the generated JSON.
Any more argument to that?
I'd prefer to have the different-skin docs in docs.rs than a custom place somewhere else.
It works, it exists, it's familiar and some people seem to be okay with it. Introducing a large change as what you propose here has a cost. So far you haven't made a case that changing the theme and all the work it requires is worth the effort. "I don't like that theme" is not good enough of a reason.
You might. Others might want something different. If you want to convince people that rustdoc should provide a different theme you will have to make an effort to convince people that it's worth it. That might mean experimenting on your own, outside of the official places.
I for one don't think a theme closer to what MDN looks like today works to transport the same information rustdoc has.
Yes, I didn't no effort or experiment so far. I just wanted to know if it'd be feasible for them to apply changes on future docs.rs docs.
It doesn't need to match exactly MDN at all though.
Small, iterative changes? Sure. Major changes that will require changing the complete layout? Very unlikely.
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.