[Merged by Bors] - Examples metadata in Cargo.toml #4741

mockersf · 2022-05-14T00:03:02Z

Objective

Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99)

Solution

Add metadata about examples in Cargo.toml
Build the examples/README.md from a template using those metadata. I used tera as the template engine to use the same tech as the website.
Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI)

Remaining To Do

After the next release with this merged in, the website will be able to be updated to use those metadata too
I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design
tracking issue: examples bevy-website#299 for other ToDos

IceSentry · 2022-05-14T00:25:26Z

I like the idea.

Assuming it gets merged, would it be possible to use the comments added in #4438 for the description?

This way there would be no duplication at all.

mockersf · 2022-05-14T00:30:12Z

Looking at a few of the doc added in #4438, some would be too long, some contains intra doc links that would just fail without rust-analyser or rustdoc. I don't think the description here and the doc there have the same goal, so probably not

alice-i-cecile

If we can, I'd really like to be able to auto-generate the table of contents and store it on a useful site. I'm sick of updating the README file and it gets really unwieldy to navigate.

Tags and search would both be incredible.

alice-i-cecile · 2022-05-14T01:11:58Z

@mockersf can you mark this as draft until it's ready so the "stuff to review" search filters work correctly?

mockersf · 2022-05-14T01:20:36Z

If we can, I'd really like to be able to auto-generate the table of contents and store it on a useful site. I'm sick of updating the README file and it gets really unwieldy to navigate.

I may do that sooner than I expected as I can't find a way to cleanly push a commit to a PR without a token...

I think I'll create a full crate for examples, each example a module, and build its doc with the dev doc website...

cart · 2022-06-22T23:16:55Z

I'm fully on board for consolidating example metadata into Cargo.toml, but I'm not a fan of adding more "auto-generated" commits. They introduce noise into our commit history, decouple "commit" from "pr" (which for a long time have been synonymous), and just generally leave me feeling a bit uncomfortable.

Instead, I think we should generate an "examples" page on the bevy website using Cargo.toml metadata, remove the current examples readme, and replace all links to the examples readme with links to the new generated bevyengine.org page.

mockersf · 2022-06-24T21:07:22Z

I'm fully on board for consolidating example metadata into Cargo.toml, but I'm not a fan of adding more "auto-generated" commits. They introduce noise into our commit history, decouple "commit" from "pr" (which for a long time have been synonymous), and just generally leave me feeling a bit uncomfortable.

👍 I'll remove that part to just leave a job checking if the page need to be regenerated, and logging what to do

Instead, I think we should generate an "examples" page on the bevy website using Cargo.toml metadata, remove the current examples readme, and replace all links to the examples readme with links to the new generated bevyengine.org page.

I agree, but I think this is quite a lot more work. The examples page is the second step in bevyengine/bevy-website#299, this PR would be just the first step. Just replacing the manually updated readme by a file updated by a tera template is a start in the right direction that isn't a lot of work when we'll remove it for a better website.

diff

cart

Love the current state of things!

Ensures the new metadata system is adopted
Removes the need to redundantly define information (thanks to the update command)
Works within the confines of the current README system while we wait for a bevy-website solution

cart · 2022-06-25T20:23:09Z

bors r+

# Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - bevyengine/bevy-website#299 for other ToDos Co-authored-by: Readme <[email protected]>

bors · 2022-06-25T20:41:48Z

Pull request successfully merged into main.

Build succeeded:

# Objective - Have information about examples only in one place that can be used for the repo and for the website (and remove the need to keep a list of example to build for wasm in the website https://github.com/bevyengine/bevy-website/blob/75acb730406ef9c5928d37daf8bb32e4dbeb8b13/generate-wasm-examples/generate_wasm_examples.sh#L92-L99) ## Solution - Add metadata about examples in `Cargo.toml` - Build the `examples/README.md` from a template using those metadata. I used tera as the template engine to use the same tech as the website. - Make CI fail if an example is missing metadata, or if the readme file needs to be updated (the command to update it is displayed in the failed step in CI) ## Remaining To Do - After the next release with this merged in, the website will be able to be updated to use those metadata too - I would like to build the examples in wasm and make them available at http://dev-docs.bevyengine.org/ but that will require more design - bevyengine/bevy-website#299 for other ToDos Co-authored-by: Readme <[email protected]>

mockersf force-pushed the examples-metadata branch from 95c0451 to a33c622 Compare May 14, 2022 00:16

mockersf added A-Build-System Related to build systems or continuous integration C-Examples An addition or correction to our examples labels May 14, 2022

mockersf force-pushed the examples-metadata branch from 92aa17b to cd19342 Compare May 14, 2022 01:09

alice-i-cecile reviewed May 14, 2022

View reviewed changes

mockersf marked this pull request as draft May 14, 2022 01:12

mockersf force-pushed the examples-metadata branch from 8271d19 to ff53b7b Compare June 14, 2022 21:21

mockersf mentioned this pull request Jun 22, 2022

tracking issue: examples bevyengine/bevy-website#299

Open

7 tasks

mockersf and others added 16 commits June 24, 2022 23:37

add metadata to a few examples

e9cb2b2

new tool to build the example readme from a template

8391748

build readme in ci

ce78311

diff

initial file

d5b50d5

Example README update

8139399

rename template so that it's not picked by the markdown lint

b36fab6

update bors

53e0f4f

update template

a5fc1b7

Example README update

bbdf46a

fix metadata paths

77877ff

prettier name

0a5bcda

split action to not happen on push

b555bef

fix package name

d279574

fix metadata path

a27ed55

change something

9f22019

remove old dependency

0303e25

mockersf added 18 commits June 25, 2022 10:11

ECS

d6252e0

games

9a2d716

input

d7c997b

reflection

2f39dcf

scene

aa0b7b2

shaders

f80b229

stress tests

2c388b5

tools

05a0aaf

transforms

7014a01

ui

2e3aa4b

window

fc0c547

name

a23f7b7

few errors

a3c7c6c

tests

29f7b19

keep the existing category descriptions

df3f303

category error

5bbaec2

switch to the actual file

b3cd11b

clippy

6de2ff5

mockersf marked this pull request as ready for review June 25, 2022 11:10

reorder some jobs

f8f176e

cart approved these changes Jun 25, 2022

View reviewed changes

alice-i-cecile added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Jun 25, 2022

bors bot changed the title ~~Examples metadata in Cargo.toml~~ [Merged by Bors] - Examples metadata in Cargo.toml Jun 25, 2022

bors bot closed this Jun 25, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Merged by Bors] - Examples metadata in Cargo.toml #4741

[Merged by Bors] - Examples metadata in Cargo.toml #4741

mockersf commented May 14, 2022 •

edited

Loading

IceSentry commented May 14, 2022 •

edited

Loading

mockersf commented May 14, 2022 •

edited

Loading

alice-i-cecile left a comment

alice-i-cecile commented May 14, 2022

mockersf commented May 14, 2022

cart commented Jun 22, 2022

mockersf commented Jun 24, 2022 •

edited

Loading

cart left a comment

cart commented Jun 25, 2022

bors bot commented Jun 25, 2022

[Merged by Bors] - Examples metadata in Cargo.toml #4741

[Merged by Bors] - Examples metadata in Cargo.toml #4741

Conversation

mockersf commented May 14, 2022 • edited Loading

Objective

Solution

Remaining To Do

IceSentry commented May 14, 2022 • edited Loading

mockersf commented May 14, 2022 • edited Loading

alice-i-cecile left a comment

Choose a reason for hiding this comment

alice-i-cecile commented May 14, 2022

mockersf commented May 14, 2022

cart commented Jun 22, 2022

mockersf commented Jun 24, 2022 • edited Loading

cart left a comment

Choose a reason for hiding this comment

cart commented Jun 25, 2022

bors bot commented Jun 25, 2022

mockersf commented May 14, 2022 •

edited

Loading

IceSentry commented May 14, 2022 •

edited

Loading

mockersf commented May 14, 2022 •

edited

Loading

mockersf commented Jun 24, 2022 •

edited

Loading