docs.rs VS awesome-bevy

Working in combination with CodeWhisperer in your IDE, you can send whole code sections to Amazon Q and ask for an explanation of what the selected code does. To show how this works, we open up the file.rs file cloned from this GitHub repository. This is part of an open source project to host documentation of crates for the Rust Programming Language, which is a language we are not familiar with.

Looks like a great initiative – I wish there was a reliable TS/JS equivalent of https://docs.rs (even considering rustdoc's deficiencies[1]).

I went through this exercise recently and so far my experience with trying to produce documentation from a somewhat convoluted TS codebase[2] has been disappointing. I would claim it's a consequence of the library's public (user-facing) API substantially differing from how the actual implementation is structured.

Typedoc produces bad results for that codebase so sphinx-js, which I wanted to use, doesn't have much to work with. I ultimately documented things by hand, for now, the way the API is meant to be used by the user.

Compare:

https://ts-results-es.readthedocs.io/en/latest/reference/api...

vs

https://tsdocs.dev/docs/ts-results-es/4.1.0-alpha.1/index.ht...

Rust Search Extension adds a section on docs.rs menubar which lists the features of a crate in a nice and easy to access format.

📝 Note: At the time of writing this post, I couldn't really locate the init function docs.rs documentation. It didn't seem easily accessible through any of the current HAL implementation documentation. Nevertheless, I reached the signature of the function through the source here.

Rust Crates are a Game-Changer 🎮:The ease of releasing a crate with `cargo publish` and the convenience of rolling out new versions amazed me. The auto-generated docs on Docs.rs. is an amazing tool, especially with docstring formatting. Doc tests serve as a two-fold tool for documenting the code and ensuring it's up-to-date.

I've found I manually type out certain subsets of URLs where possible[0], maybe that's subconsciously associated with my impression that Google Search results have gotten worse and worse over the years.

[0] https://en.wiktionary.org/wiki/ and https://docs.rs/ come to mind.

docs.rs also downloads you crate automatically to generate docs and I would guess lib.rs does something similar

There are also a few key sites you'll want to keep in your back pocket at all times: - The Standard Library Documentation has complete documentation for every std library function in Rust - crates.io is a repository for all third-party packages, and docs.rs has human-readable documentation for the overwhelming majority of them - The Rust Cookbook has some code examples for common tasks you may need to perform - Make sure you are using clippy, which is available through Rustup and can be run with cargo clippy as a replacement to cargo check, it adds additional lints for your Rust code and is very helpful for teaching many of the best practices

OTOH, source-code-generated-docs normalize how code docs are, like the rust docs.rs paradigm, so it sort of forces or encourages package creators/maintainers to write docs.

Among Bevy contributors (including myself) there is a general hesitance to invest too much time in official learning material that will be obsolete by the next release. Bevy's APIs are beginning to stabilize ... and the appetite (both from users and from Bevy devs) for official material is increasing. The time is coming (soon)!

While you wait, there are a sizeable number of tutorials on YouTube, and we have learning material linked in https://bevyengine.org/assets/#learning as well.

User code is the same as engine code. It's all Rust. Consequently, Bevy already has a surprisingly rich ecosystem

I've summarized a lot of my thoughts in this blog post, but in short: * "The Developer's Engine": most engines are built using multiple languages, with significant abstraction between "user code" and "engine code". Bevy is built with a consistent stack and data model (see the blog post I linked to for details). If you "go to definition" on a Bevy app symbol in your IDE, the underlying engine code will look the same as your app code. You can also swap out basically everything. We have a vibrant plugin ecosystem as a result. These blurred lines also make it way easier for "Bevy app developers" to make direct contributions to the engine. Bevy App developers are Bevy Engine developers, they just don't know it yet. The new Bevy renderer (in 0.6) was also built with this principle in mind. It exposes low, mid, and high level renderer apis in a way that makes it easy to "insert yourself" into the engine. * Fully embraces ECS: No popular engines are currently all-in on ECS (either they have no official support ... or they are half-in half-out). I reflect on some of the benefits we've enjoyed thanks to Bevy ECS in the blog post I linked to. Note that there is a lot of pro and anti ECS hype. Don't just blindly follow dogma and hype trains. ECS isn't one thing and Bevy ECS intentionally blurs the lines between paradigms. * Fully Free and Open Source With No Contracts: Of the popular engines, only Godot is a competitor in this space.

I would recommend going to bevy's blog post(https://bevyengine.org/news/) since the update lists are the only convenient way I know it find out what features bevy actually has implemented directly. then go over to bevy assets(https://bevyengine.org/assets/) and you can see the community-made plugins to get an idea of the sorts of things people are making available to you. and finally, as a bit of self-promo, I have a youtube series called bevy basics where I got over how bevy does things, like the ECS and systems, moving into more direct use thing like getting user input you can fine it all here www.youtube.com/playlist?list=PL6uRoaCCw7GN_lJxpKS3j-KXuThRiSXc6

I've summarized a lot of my thoughts in this blog post: https://bevyengine.org/news/bevys-first-birthday/#things-i-m...

But in short (slight copy-paste of my generic Bevy pitch):

The Developer's Engine: most engines are built using multiple languages, with significant abstraction between "user code" and "engine code". Bevy is built with a consistent stack and data model (see the blog post I linked to for details). If you "go to definition" on a Bevy app symbol in your IDE, the underlying engine code will look the same as your app code. You can also swap out basically everything. We have a vibrant plugin ecosystem (https://bevyengine.org/assets) as a result. These blurred lines also make it _way_ easier for "Bevy app developers" to make direct contributions to the engine. Bevy App developers _are_ Bevy Engine developers, they just don't know it yet. The new Bevy renderer (in 0.6) was also built with this principle in mind. It exposes low, mid, and high level renderer apis in a way that makes it easy to "insert yourself" into the engine.

Fully embraces ECS: No popular engines are currently all-in on ECS (either they have no official support ... or they are half-in half-out). I reflect on some of the benefits we've enjoyed thanks to Bevy ECS in the blog post I linked to. Note that there is _a lot_ of pro _and_ anti ECS hype. Don't just blindly follow dogma and hype trains. ECS isn't one thing and Bevy ECS intentionally blurs the lines between paradigms.

We can't currently compete with the "big engines" on features, but we are adding features at a rapid (and growing) pace. Bevy was released about a year and a half ago. Most popular engines have been in development for almost 20 years (Godot since 2007, Unity since 2005, Unreal since 1998), so we have plenty of "time" from my perspective.

I'm a huge fan of Godot and used it to build my game High Hat over the course of about 4 years. I also contributed to it every once and awhile. When I was initially building Bevy, Godot's design decisions were always at the top of my mind (and they still are to this day). I love they way they do scenes (and our system draws inspiration from it). We also plan on borrowing their "dogfooding" approach to editor building (the Bevy Editor will be a normal Bevy App).

Bevy still has functionality gaps in most areas. And we still warn developers about stability and missing features in our learning material. But many people are successfully making games with Bevy at this point. Some companies are already successfully building on Bevy for commercial projects. Our modular "everything is a Rust plugin" approach means that most gaps can be filled with 3rd party plugins, and we already have a large ecosystem of people doing that: https://bevyengine.org/assets/.

One of the benefits of 4.0 is also the modularity of it with GDExtension. The major parts of the engine (including the physics) can be swapped with replacements without the need to recompile the entire engine. I'd usually say that is a long shot for community run projects, but even Bevy engine has community made extensions for separate physics engines.

https://bevyengine.org/assets/#physics

Forgetting about extensions, though, I see your point and almost agree, but Godot has shown that they will put in the work to improve their project, even if that means removing features like they did with visual scripting. Their physics engine will definitely be rough at first, but based on their past work, I believe they are willing and able to maintain it.

Lots of good community-developed networking plugins over in Bevy Assets

Hi all! In the Assets tab from the Bevy official website, there is a "Making a Chess Clone in 3D" tutorial to learn Bevy written by guimcaballero. Unfortunately it was written in Bevy 0.4.0 and using bevy_mod_picking 0.3.1.