`bevy doc` - an ECS project documentation generator

[IQuick143]

What?

I think it would be nice to have a tool that would be able to generate Bevy (ECS) oriented documentation from project source files.

Some things this documentation should (help) answer:

• What are all the systems and Components in a project? (documentation, navigation)
• Which systems (mutably?) access this Component/Event/Resource? (documentation, debugging)
• What is the required-components dep tree for a Component? (documentation)
• What plugin initialises this Event/Resource? (project structure docs, navigation, debugging)
• What plugin does this system belong in? (project structure docs)
• Where is X system for Y task? (navigation, documentation)
• TODO: More ideas / curate the list

Some things this documentation alone is not intended for (some of these could be done by integrating with cargo doc and linking to there):

• What are all the trait (incl. non-bevy) implementations on this type?
• Bevy API docs
• Documentation on types that are not ECS relevant or that don't carry semantics special to Bevy
• TODO: more examples

Why?

Collecting the information about a bevy project involves many many declarations as well as many App method calls. (plugins (method bodies), Components (declarations and attributes), Resources (declarations, attributes and App registration), systems (function signatures and App registration), Events, and so on...) Bevy projects are recomended to be highly modular and split up, which is in many regards good, but it means that all this information becomes spread out across many files, and worse (in my experience) it becomes dilute. (ex: you need to read the system signatures, but the system bodies are irrelevant to you.)

Even if it's reasonably easy to find what you need by following Type information breadcrumbs via go-to-reference and go-to-declaration, this involves a lot of jumping around, and in my experience does not lend itself to learning the overall structure of the project.

How?

I don't know how difficult it would be to implement, I imagine the biggest challenge is reading and collecting all the required information about how the App is constructed (TODO: What if the user has no bevy_app, can we still learn useful information from things like Schedule::add_systems?) Many other pieces of information should be relatively easy to parse (such as Component declarations and their attributes.)

[BD103]

I would love to see this! I believe someone made of a demo of this a few months back, it integrated with Rustdoc's metadata output directly.

[BD103]

You may be able to use Miri combined with an introspection plugin, but I've never done such a thing before.

[BD103]

As @IQuick143 mentioned on Discord, we could also have a CLI version of this. E.g.:

bevy list [components|systems|resources|events|plugins|etc..]

[benfrankel]

For systems this may be challenging:

• "Normal" functions like fn foo() {} are valid systems, so type signature isn't enough and you need to look for .add_systems specifically.
• .add_systems calls may be hidden behind feature flags, dead code, plugins that are conditionally added, etc. at runtime. It's probably fine to assume that xyz is a system if it's in an .add_systems call, even if that call never runs, though.
• The same system can be added multiple times, to the same or different schedules.
• Function pointers and closures can be added as systems.
• Observers and one-shot systems are still "systems".

One pathological example:

let i = foo;
let j = bar;
app.add_systems(if x > y { Update } else { PreUpdate }, if y > z { i } else { j });

[IQuick143]

I agree that systems are rather challenging. Considering anything that goes into .add_systems() to be a system seems good to me, although it does have drawbacks, and it's true that we can't always decide what system goes into what schedule (although I have not seen anyone write code like that pathological example).

I think we just need to add some sort of override/hint system, so that users can explain their pathological examples if they do occur.

Observers and one-shot systems could IMO get a different section in the docs, but documenting these would also be important.