bevy_mocks crate

[stepancheg]

Objective

To be able to write illustrative examples in bevy crates which do not depend on each other.

For example, to write good examples in bevy_ecs crate, we really need dependencies on crates like bevy_app or bevy_pbr.

dev-dependencies are used in doctests. Also dev-dependencies can be cyclic (e.g. bevy_ecs can dev-depend on bevy_app), but such crates cannot be published.

Solution

The proposed solution is to add bevy_mocks crate which basically contains bevy crate API with mock implementations.

So doctests won't really test much, but are useful as published code examples.

[Nilirad]

Interesting, but I'm on the idea that bevy_ecs docs should primarily cover bevy_ecs usage, not Bevy crates that depend on bevy_ecs. However, since the entire Bevy engine is strongly cohesive, I think it is fair to use items in examples that are on dependent crates (to a limited capacity).
Though honestly, I don't know if it's worth it to create a whole set of mock elements for just a couple of cases. Plus, if the original item changes, it should be manually be changed in bevy_mock, which is a significant burden. I would rather wait that the dev-dependencies issue gets resolved.

[stepancheg]

I don't know if it's worth it to create a whole set of mock elements for just a couple of cases

It has been countless times when I saw API and don't understand how to use, so had to to read the sources. Simple examples help I believe.

It is a couple cases yet, should be much more.

if the original item changes, it should be manually be changed in bevy_mock, which is a significant burden

I believe maintaining these mocks would be less trouble than writing good documentation and keeping it up to date.

I would rather wait that the dev-dependencies issue gets resolved.

The issue was created in 2017, so I don't expect it to be resolved soon.

Bottom line is: I would be happy if there was better solution.

[alice-i-cecile]

I would rather wait that the dev-dependencies issue gets resolved.

Agreed with @stepancheg; I don't think that's a particularly viable path forward given the duration it's been open and the resourcing levels of the rust-docs team.

No strong feelings on this PR: I could see an argument for either.

Actually, I think my preferred solution is just to fold bevy_app into bevy_ecs, which solves this (and many other) problems. See #3786.

[stepancheg]

Pulling bevy_app into bevy_ecs would solve this issue.

Closing this for now. Can reopen later if there's stronger opinion for this solution.