[Merged by Bors] - Add readme as docs to relevant crates. #2575

Hoidigan · 2021-07-31T17:19:46Z

There are only READMEs in the 4 crates here (with the exception of bevy itself).
Those 4 crates are ecs, reflect, tasks, and transform.
These should each now include their respective README files.

alice-i-cecile

Awesome, thank you!

alice-i-cecile · 2021-07-31T19:38:22Z

bors try

bors · 2021-07-31T20:01:59Z

try

Build failed:

build-android

Nilirad · 2021-08-01T14:29:14Z

I tried to do the same on my #2365 PR, but the examples in README.md break the doc test suite 😕

alice-i-cecile · 2021-08-01T14:40:21Z

@mockersf, any ideas on how to work around this CI issue?

Nilirad · 2021-08-01T14:56:48Z

It's not only a CI issue though. Running a simple command like

cargo test -p bevy_ecs --doc

would fail.

Hoidigan · 2021-08-01T15:30:02Z

We could ignore the doc tests? Put " ```rust ignore " for the start of the blocks instead of " ```rust "
Either that or go through and put the lines that get ignored but make the doc test work. I'm not sure if github would still show them or not, though.
(https://doc.rust-lang.org/rustdoc/documentation-tests.html#hiding-portions-of-the-example)

alice-i-cecile · 2021-08-01T15:32:33Z

I'm not sure if github would still show them or not, though.

Yeah, I think Github is likely to just show the extra lines of code :( Let's try ignoring them; it's no worse than the current situation where they're never compiled.

Nilirad · 2021-08-01T15:35:36Z

I don't know if ignoring will retain the code highlighting on GitHub renders...

Hoidigan · 2021-08-01T15:41:45Z

Hmmm, yeah I don't know either.
I'll try a few and see.

alice-i-cecile · 2021-08-01T15:45:29Z

https://github.com/bevyengine/bevy/blob/9f096ecb830b15943bef87d520e1c696de6868e7/crates/bevy_ecs/README.md works!

Hoidigan · 2021-08-01T15:45:59Z

I'll go through and grab the rest then 😄

Ignore the doc tests in the readme, this allows "cargo test --doc -p *" to run without errors

Hoidigan · 2021-08-01T15:52:06Z

Alrighty they should be ignored now, cargo test --doc -p * worked fine for me.

mockersf · 2021-08-09T19:49:00Z

I'm not a fan of ignoring the failing code examples as a big plus of including the README is to test those examples. Would it be hard to fix them?

Hoidigan · 2021-08-09T20:21:09Z

The issue wasn't that they would be hard to fix (I don't think so but I'd need to check again once I can) but that if we fixed them we'd either clutter up examples in the docs and GitHub, or we'd do the hide lines thing for docs.rs but it would show the lines still on GitHub.

It's up a little bit in the conversation, we talked about it.

mockersf · 2021-08-09T20:28:08Z

It's up a little bit in the conversation, we talked about it.

Yup, but it depends: is allowing the code blocks to work just adding 2 lines of imports? I think that's worth it. Is it adding 20 lines of setup? Ok that can be ignored, or maybe the example can be reworked?

Hoidigan · 2021-08-09T20:31:53Z

I'm not entirely sure and I'm not in a position to check right now, but in the next day or two I should be able to see. (Maybe tonight, I don't know.)

Hoidigan · 2021-08-10T13:28:33Z

Alrighty, so I went through and made the examples work.
There were some things I was a little iffy about, namely declaring Position and Velocity for a lot of examples in bevy_ecs, but that fits in two lines. Most of them were solved by that and importing the prelude.
I did take bevy_core as a dev dependency to bring in the time resource.
Bevy_ecs does now have all working examples and none ignored. Most of them are only 3 or 4 lines longer. (and there was a few actual errors in them too, so that's fixed now.)

bevy_reflect has all of the setup at the top example. I could go through and copy and paste it into every other example but that's the 20 lines of setup we wanted to avoid.
Would it be possible (or wanted) to create a small crate inside of reflect and then have a dev-dependency on that for some setup function and imports?

Tasks and transform had no examples so that's easy enough.

NiklasEi

Good call to include the Readmes, thanks!
Can we try to keep the Readme examples of bevy_ecs free of other bevy crates? I think of this Readme as showing examples of how to use bevy_ecs standalone in e.g. other engines or completely different contexts than gamedev.

NiklasEi · 2021-10-08T07:51:35Z

crates/bevy_ecs/README.md

@@ -68,11 +87,17 @@ fn print_position(query: Query<(Entity, &Position)>) {
 Apps often require unique resources, such as asset collections, renderers, audio servers, time, etc. Bevy ECS makes this pattern a first class citizen. `Resource` is a special kind of component that does not belong to any entity. Instead, it is identified uniquely by its type:

 ```rust
+use bevy_ecs::prelude::*;
+
+// Bevy does provide its own more advanced Time as a resource, but we


Bevys' Time is part of the core crate. I would prefer keeping this readme purely for bevy_ecs, so I would remove this comment here.

NiklasEi · 2021-10-08T07:52:26Z

crates/bevy_ecs/README.md

@@ -174,6 +211,9 @@ fn system(query: Query<&Position, Added<Velocity>>) {
 Resources also expose change state:

 ```rust
+use bevy_core::Time;


See comment above. Can we get rid of the bevy_core dependency?

NiklasEi · 2021-10-18T22:09:25Z

@alice-i-cecile could we add this to 0.6? It would be nice to have the readmes in the official documentation of the next release. And the change is pretty uncontroversial I would say.

NiklasEi · 2021-11-23T22:24:51Z

@Hoidigan could you add #3005 as getting resolved by this PR?

Hoidigan · 2021-11-23T22:29:16Z

Fixes #3005

(that is how you do that, right? Just put that here?)

NiklasEi · 2021-11-23T22:31:55Z

Fixes #3005

(that is how you do that, right? Just put that here?)

I think it needs to be in the commit message. So in this case in the PR description.

cart · 2021-12-18T22:26:10Z

crates/bevy_ecs/README.md

 #[derive(Default)]
-struct Time {
-    seconds: f32,


I object to using a tuple struct here. The named field is way better at documenting intent. Tuple structs rarely have a place in public apis imo.

Sounds good to me 👍

cart · 2021-12-18T22:26:28Z

One small comment. Everything else looks good to me!

cart · 2021-12-18T22:59:41Z

bors r+

Fixes #2566 Fixes #3005 There are only READMEs in the 4 crates here (with the exception of bevy itself). Those 4 crates are ecs, reflect, tasks, and transform. These should each now include their respective README files. Co-authored-by: Hoidigan <57080125+Hoidigan@users.noreply.github.com> Co-authored-by: Daniel Nelsen <57080125+Hoidigan@users.noreply.github.com>

bors · 2021-12-18T23:12:07Z

Pull request successfully merged into main.

Build succeeded:

Add readme as docs to relevant crates.

2c1e4c8

github-actions bot added the S-Needs-Triage This issue needs to be labelled label Jul 31, 2021

alice-i-cecile added C-Docs An addition or correction to our documentation and removed S-Needs-Triage This issue needs to be labelled labels Jul 31, 2021

alice-i-cecile approved these changes Jul 31, 2021

View reviewed changes

bors bot added a commit that referenced this pull request Jul 31, 2021

Try #2575:

2f50d16

Try ignoring a few docs for github

9f096ec

Fix failing doc tests

664a47e

Ignore the doc tests in the readme, this allows "cargo test --doc -p *" to run without errors

Nilirad added a commit to Nilirad/bevy that referenced this pull request Aug 7, 2021

Remove ECS crate level docs as done by bevyengine#2575

96ff662

Unignore and fix examples in bevy_ecs readme

8d74220

alice-i-cecile added the S-Needs-Review label Sep 22, 2021

Hoidigan and others added 2 commits October 7, 2021 12:18

Merge branch 'main' into crate-level-docs

f9ffc73

fix bevy_ecs cargo.toml

bad2acd

fix bevy_ecs readme tests

f99e519

NiklasEi reviewed Oct 8, 2021

View reviewed changes

Remove bevy_core and update readme

903e2a6

NiklasEi approved these changes Oct 8, 2021

View reviewed changes

NiklasEi added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Needs-Review labels Oct 8, 2021

IceSentry approved these changes Oct 8, 2021

View reviewed changes

alice-i-cecile added this to the Bevy 0.6 milestone Oct 18, 2021

mockersf mentioned this pull request Oct 22, 2021

Bevy ECS readme: not working example due to missing #[derive(Component)] #3005

Closed

DJMcNab mentioned this pull request Nov 6, 2021

Fixed ECS example compilation issues #3083

Closed

jamesbeilby mentioned this pull request Nov 10, 2021

Updated Bevy ECS readme #3100

Closed

DJMcNab mentioned this pull request Dec 8, 2021

Fix bevy_ecs README.md #3279

Closed

Merge branch 'bevyengine:main' into crate-level-docs

c3549d4

cart reviewed Dec 18, 2021

View reviewed changes

Hoidigan added 2 commits December 18, 2021 14:43

Merge branch 'bevyengine:main' into crate-level-docs

d86f533

add suggested rename

0743c59

bors bot changed the title ~~Add readme as docs to relevant crates.~~ [Merged by Bors] - Add readme as docs to relevant crates. Dec 18, 2021

bors bot closed this Dec 18, 2021

Hoidigan deleted the crate-level-docs branch December 18, 2021 23:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Merged by Bors] - Add readme as docs to relevant crates. #2575

[Merged by Bors] - Add readme as docs to relevant crates. #2575

Hoidigan commented Jul 31, 2021 •

edited

Loading

alice-i-cecile left a comment

alice-i-cecile commented Jul 31, 2021

bors bot commented Jul 31, 2021

Nilirad commented Aug 1, 2021

alice-i-cecile commented Aug 1, 2021

Nilirad commented Aug 1, 2021

Hoidigan commented Aug 1, 2021 •

edited

Loading

alice-i-cecile commented Aug 1, 2021

Nilirad commented Aug 1, 2021

Hoidigan commented Aug 1, 2021

alice-i-cecile commented Aug 1, 2021

Hoidigan commented Aug 1, 2021

Hoidigan commented Aug 1, 2021

mockersf commented Aug 9, 2021

Hoidigan commented Aug 9, 2021 •

edited

Loading

mockersf commented Aug 9, 2021

Hoidigan commented Aug 9, 2021

Hoidigan commented Aug 10, 2021 •

edited

Loading

NiklasEi left a comment

NiklasEi Oct 8, 2021

NiklasEi Oct 8, 2021

NiklasEi commented Oct 18, 2021

NiklasEi commented Nov 23, 2021

Hoidigan commented Nov 23, 2021 •

edited

Loading

NiklasEi commented Nov 23, 2021

cart Dec 18, 2021

Hoidigan Dec 18, 2021

cart commented Dec 18, 2021

cart commented Dec 18, 2021

bors bot commented Dec 18, 2021

[Merged by Bors] - Add readme as docs to relevant crates. #2575

[Merged by Bors] - Add readme as docs to relevant crates. #2575

Conversation

Hoidigan commented Jul 31, 2021 • edited Loading

alice-i-cecile left a comment

Choose a reason for hiding this comment

alice-i-cecile commented Jul 31, 2021

bors bot commented Jul 31, 2021

try

Nilirad commented Aug 1, 2021

alice-i-cecile commented Aug 1, 2021

Nilirad commented Aug 1, 2021

Hoidigan commented Aug 1, 2021 • edited Loading

alice-i-cecile commented Aug 1, 2021

Nilirad commented Aug 1, 2021

Hoidigan commented Aug 1, 2021

alice-i-cecile commented Aug 1, 2021

Hoidigan commented Aug 1, 2021

Hoidigan commented Aug 1, 2021

mockersf commented Aug 9, 2021

Hoidigan commented Aug 9, 2021 • edited Loading

mockersf commented Aug 9, 2021

Hoidigan commented Aug 9, 2021

Hoidigan commented Aug 10, 2021 • edited Loading

NiklasEi left a comment

Choose a reason for hiding this comment

NiklasEi Oct 8, 2021

Choose a reason for hiding this comment

NiklasEi Oct 8, 2021

Choose a reason for hiding this comment

NiklasEi commented Oct 18, 2021

NiklasEi commented Nov 23, 2021

Hoidigan commented Nov 23, 2021 • edited Loading

NiklasEi commented Nov 23, 2021

cart Dec 18, 2021

Choose a reason for hiding this comment

Hoidigan Dec 18, 2021

Choose a reason for hiding this comment

cart commented Dec 18, 2021

cart commented Dec 18, 2021

bors bot commented Dec 18, 2021

Hoidigan commented Jul 31, 2021 •

edited

Loading

Hoidigan commented Aug 1, 2021 •

edited

Loading

Hoidigan commented Aug 9, 2021 •

edited

Loading

Hoidigan commented Aug 10, 2021 •

edited

Loading

Hoidigan commented Nov 23, 2021 •

edited

Loading