feat: added rust api documentation

[simonhyll]

Adds the Rust API directly into the website!

Stream where I develop it in: https://www.youtube.com/watch?v=1M0vsXRKa9I&ab_channel=SimonHyll

The current approach requires running a custom little Rust program I made called tauri-json. Ideally we won't be using it for various reasons but instead make it part of our CI/CD one way or another, it can even simply be added as a part in build.rs to generate the json output so we can host them in the actual repositories instead. The alternative is doing some form of Tauri CLI sort of setup for prebuilding the tool, an approach that might be more interesting if we decide to expand this to more crates than just tauri.

1. pnpm i -r
2. pnpm dev:setup
3. cd packages/tauri-json && cargo run
4. pnpm --filter rust-api-generator run build
5. pnpm dev

Todo:

• Set up types for all types in rustdoc.index
• Generate pages for all types, not just modules
• Figure out how we'll best handle linking to external crates

[netlify]

❌ Deploy Preview for tauri-docs-starlight failed.

Name	Link
🔨 Latest commit	5101966
🔍 Latest deploy log	https://app.netlify.com/sites/tauri-docs-starlight/deploys/64f36a0ed996d70008d00d38

[simonhyll]

While resolving the merge I noticed a switch in folder structure from core to just js and rust. I'll have to fix that.

[lorenzolewis]

While resolving the merge I noticed a switch in folder structure from core to just js and rust. I'll have to fix that.

Yeah, that was one that we switched over recently after Tuesday's Discord call, good catch.

[lorenzolewis]

A few thoughts that I have taking a quick look so far:

I like the pages being split up per-module, this reflects what we have on the JS API docs. What are your thoughts on including all of a module's objects inline on the page? This is one for instance: https://deploy-preview-1400--tauri-docs-starlight.netlify.app/2/reference/rust/tauri/app/

Instead of having each of those Structs pointing to a separate page would we be able to build them out with a similar structure/order as this page for example: https://deploy-preview-1400--tauri-docs-starlight.netlify.app/2/reference/js/core/namespaceevent/

The last thing is much more cosmetic, but the typedoc generator has this bit of logic which is recently added that's really nice: https://github.com/tgreyuk/typedoc-plugin-markdown/blob/ace1b92284a6575141c3ce6d15a8fd7c3813b0e6/packages/typedoc-plugin-markdown/scripts/build-options.ts#L45

It will pick up the project's prettier config and run the files through it before writing to disk. This is sooooo nice so you don't have to fight with formatting, CI checks, etc.

[simonhyll]

Sent a bit of pushback on Discord about making Rust more like JS, I'd want it more the other way around 😅Open to negotiation though

The Prettier thing I can certainly look into 🙂

[lorenzolewis]

Putting a few notes from a side convo here:

Complex: need their own page

• Module
• Struct
• Enum
• Trait

Simple: inline on the respective module page

• Macro/attribute
• Constants
• Functions
• Re-exports, just link to the respective source

[amrbashir]

I really don't think it is worth doing this PR tbh, and I would advise against it. docs.rs is already an amazing documentation website and I am not trying to stop you re-inventing the wheel, maybe you can do a better job than docs.rs, but I just wanted to maybe stop for a moment and decide whether it is worth it or not and to also give a few points to discuss:

• Rust is pretty advanced than javascript/typescript and its documentation and markdown simply doesn't have enough capabilities, think of this section for example, https://docs.rs/tauri/latest/tauri/struct.Menu.html#blanket-implementations, to replicate something that is acceptable, it will be a huge code block and won't look pretty nice as a DX since you can't link to a specific impl block that is withing a code block (correct me if I am wrong) and if we were to split it to multiple code blocks it won't look nice at all.
• Rust users really prefer the consistency of the ecosystem and I can say that 90% of rust users prefer to read the crate documentation on docs.rs rather than any other site or sometimes the official README.md and I don't think we should encourage anyone to diverge from that.

I am aware that this PR addresses the folks new to Rust or we want to just have a seamless integration between JS/TS and Rust docs so I would instead suggest taking the output of cargo doc and maybe integrate it into the website, with our custom theme and colors while keeping the general structure of the documentation as is and maybe integrate it in a way that keeps our sidebar and header visible so you can quickly jump to other guides or JS/TS APIs.

Again I am not really trying to discourage any efforts in this direction, just want to be sure of the direction so we don't regret it later.

[lorenzolewis]

Thanks for the input @amrbashir 💜

Here's a few of my thoughts around this area (but not meant as a "yes/no" to this particular work):

• We've heard feedback from the JS community that jumping into Rust can be overwhelming. While Tauri is a great opportunity for someone to learn Rust, I do think making Tauri as approachable as possible is something for us as Working Group to hold in mind
• One of the ways we could do that is to make sure as much Tauri functionality as possible is also accessible via the JavaScript side. A good example of this is the https://beta.tauri.app/2/guide/notification/ guide where we show how to do a specific thing in both JS and Rust (although the Rust part is currently a placeholder 😅 )
• Offering an approachable way to get into Rust was one of the points I had in mind to rolling our own Rust API docs, but I don't think we paused (especially after merging the Notification guide) to think about if this is something that's really still needed or if the new feature/plugin guides help alleviate some of that pain
• Another way we can make Tauri more approachable to the JS community are through things like [feat] 2.0: Add plugin to lib.rs with tauri plugin add tauri#7696 that really go to improve the DX for those types of users

Again, not a yes/no on this, I'll leave that up to @simonhyll to decide based on his time/capacity, but let's keep these points in mind especially when thinking of capacity and priority.

---

Maybe a different way to spend this effort would be to contribute in rust-lang/rust#76578 and https://rust-lang.github.io/rfcs/2963-rustdoc-json.html to help stabilise this? I'm sure that would also help unlock the potential for other projects to jump in and build an ecosystem around Rust documentation in the future that we could use if we wanted to approach this (similar to how we see with typedoc, typedoc-plugin-markdown, typedoc-plugin-mdn, etc.)

[simonhyll]

• Using mdx we have the ability to customize appearance however we want. I used markdown for simplicity sake, but it's a piece of cake to switch to mdx and using custom components to style any part however we want. Styling wise I don't see anything in the page you linked @amrbashir that we can't do ourselves, we're not limited by what markdown can provide. In fact we can output it as Astro, Vue or whatever else we need. The system I'm developing decouples the parsing of the json file from the page generation process sufficiently where it's pretty simple to change file names and contents.
• I agree that most Rust users will keep using docs.rs, but this isn't really meant for them. There are tonnes of users that absolutely hate docs.rs, I've had users tell me they simply skipped going to docs.rs because they simply assume right off the bat that it's too advanced and difficult for them to find anything in, letting me play the part of searching docs.rs for them. This is an effort to make things approachable and easy for the non-Rust users, so what Rust users will do isn't much of a factor.
• I've looked at using the output of cargo doc before, and while it's not impossible to do it's by no means more stable or easier to user than the json version I'm using in this PR, at least not if you want to transform it at all. Just adding it as an iframe or something like that isn't really an option because the problem we want to solve isn't just getting the documentation on the same site as everything else, we want to make sure it's more approachable, and that's a transformative operation. We need to alter how the references are structured so they are easier for people to view. If all we did was literally recreate docs.rs then there wouldn't be any point to make any of this because then it wouldn't be more accessible to the beginners. Plus when it's made as a part of the site the search functionality in Starlight picks up on it as well.

My time is rather limited nowadays, which to me is the bigger factor of whether this should be closed or not. The feature itself has received more than enough of a positive response to be desired to be developed one way or another, the question is just if I have the time to do it, and whether as Lorenzo says if we want to make it as a part of the tauri-docs project or if I should look into making it a completely separate project and contribute towards Rust documentation at large instead.

In my opinion it doesn't hurt to keep the PR up so I can tinker with it when I have the time for it, but odds are I'll make it a separate project sooner or later anyway, so imo it's up to you @lorenzolewis if you want me keep working on this inside tauri-docs or if you want me to develop a separate project and later on PR us implementing that project in tauri-docs.

[lorenzolewis]

You already hit on the point @simonhyll but my biggest thought (concern?) with this is time it takes to build and priority. At the end of the day it's OSS and the beauty of that is that anyone can work on whatever specific project their passion is in (whether docs, code, digging into Rust AST, etc.).

Looking at a bit of a higher-level, this is where my head is at:

• rustdoc JSON isn't stabilised yet (Tracking issue for RFC 2963: rustdoc JSON backend rust-lang/rust#76578)
  • I think as Tauri it's a golden opportunity for us to start joining into some of these RFCs upstream and seeing if we can help with our efforts there
  • By getting this in upstream, we could benefit from it (if we decide to build something), but more importantly the Rust ecosystem could benefit from it
  • I think if that's stabilised then over time we'll see more projects popping up that really focus on building out multiple doc systems (one of those very much could be yours @simonhyll )
• We have a really sizable chunk of work that we need to focus on to get to 2.0 stable on the docs side. I put this together over the weekend to start tracking progress towards it: https://github.com/tauri-apps/tauri-docs/milestone/4
• There's an existing solution (docs.rs) that at least gives us Rust API documentation, so I see this as a "nice to have" not a "need to have" for where we are now, whereas getting all the guides written is a "need to have"
• To help with support, I feel that efforts like https://beta.tauri.app/2/guide/notification/ go a really long way to making Rust more approachable for people (even though the Rust part of that is a TODO: right now 😅)
  • Personally, as a non-Rust developer myself, I struggle with docs.rs being overwhelming and not knowing where/how to get started with a particular thing
  • https://beta.tauri.app/2/guide/notification/ helps with that by giving the reader a strong starting foundation to begin with, shows which APIs are important, and then we can point to the relevant docs from there for them to poke around after they get something up and running

To more directly speak to your points @simonhyll:

• I'm going to skip over the UI/UX, MDX, JSON vs. rustdoc bits, those are implementation details that are important but don't think we're there yet to discuss them imo (although they are important if/when we get there)
• Time (and what we prioritize in that time) is the most important bit. I honestly believe time spent working on items in https://github.com/tauri-apps/tauri-docs/milestone/4 would be much more impactful leading up to 2.0
• From the context of "what's in the tauri-docs repo", I'd see this being a separate npm package that we import as that would make it a lot easier for others to potentially contribute and benefit directly from it
• I'm an inbox-zero kind of guy so I see a PR (even if it's in draft state or not) as something I should jump in and either work on or figure out what I can do to help drive it forward (dang PM hat). Maybe we could file this as an issue and develop this under your fork @simonhyll until you want to move it into it's own separate package/repo? I'd love to stay involved (and I'm sure that many people in the rest of the community would as well)

To sum up what I'd do:

1. File this as an enhancement issue in this repo and point to your fork @simonhyll
2. Close this PR (because inbox-zero and my OCD 😅)
3. Really focus on getting through everything in https://github.com/tauri-apps/tauri-docs/milestone/4
4. See if/how we could help with Tracking issue for RFC 2963: rustdoc JSON backend rust-lang/rust#76578
5. Pick it up from there after the above and see where we're at

---

On a more personal note, I really hope that we're taking this conversation as a way to see what we need to prioritize to get Tauri to the next level, and not a conversation to rain on amazing ideas and projects. I 100% see the need for this and can see a bright future where we can make an amazing Rust API documentation thingy, but we just need to make sure we laser-focus on a few other things first. And thank you @amrbashir for keeping us grounded.

Feel free to send me a message if you'd like around any of this, I'll leave it up to you to decide and do anything from here 💜

[simonhyll]

Closing this in favour of inbox-zero OCD and moving it to a separate project. :)

[amrbashir]

I feel like the general consensus here is making rust approachable for new comers and be able to search it from within our site which is great, I am all for it but IMO would hurt them in the long-run if they get used to our solution because our DX will break as soon as the user needs another crate or if he even clicks on a type that is not in our crate and it will take him to docs.rs later or sooner where he will spend most of his time checking documentation for other crates anyways. I think this might be a good way to introduce users to rust but we don't have any data to decide whether it will indeed help them or not and we can't know unless we try and that's why I am not totally opposed to the idea.

I am not saying docs.rs is the best but is really good IMO and far better than any language documentation I ever used and rolling our own could potentially fragment the ecosystem and I would rather see contributions upstream to help the general ecosystem by analyzing why some users hate it and how could we improve upon it (which I assume you already have an idea about).