Use same docs, for CI and deployment #12692

ameknite · 2024-03-24T21:16:34Z

Objective

In Make feature(doc_auto_cfg) work #12642, I broke deploy docs, because bevy CI settings for CI is different that the settings for Deploy Docs
Fixes Consider validating that docs can build as on docs.rs in CI #12379

Solution

unify doc settings for CI and Deployment
A new flag --deploy-docs was added.
Now it build docs in nightly:
CI: cargo r -p ci -- doc-check --nightly. Build docs with --workspace
Deploy: cargo r -p ci -- doc-check --nightly --deploy-docs. Build docs with -p bevy
Fix some warnings to pass CI.

BD103

I have a few questions and a couple of suggestions. Sorry for the delay, I was away for the past few days. :)

BD103 · 2024-03-30T03:48:56Z

Cargo.toml

@@ -1128,6 +1128,7 @@ wasm = true
 [[example]]
 name = "log_layers"
 path = "examples/app/log_layers.rs"
+doc-scrape-examples = true


Is this meant to be set to false? I believe the default is true, so this is redundant unless I'm missing something.

Docs, for future me's reference

I was getting a warning to add the text.
Before adding doc-scrape-examples = true, the docs in those examples was not being checked by cargo doc

Odd, I wonder why those examples were getting skipped. Could you send a screenshot of the error message? Perhaps it will give further insight...

crates/bevy_winit/src/winit_config.rs

examples/app/log_layers_ecs.rs

src/lib.rs

examples/app/log_layers_ecs.rs

.github/workflows/ci.yml

mockersf · 2024-03-31T19:51:40Z

tools/ci/src/main.rs


        test_suite.insert(
            Check::DOC_CHECK,
            vec![CITest {
-                command: cmd!(sh, "cargo doc {args...}"),
+                command: cmd!(sh, "cargo +nightly doc {args...}"),


it's a pain to require nightly in the tools. if it's launched using stable, it should keep on stable and not stealthily use a nightly

it's not the first place it's used in this script, I would rather that this would be fixed rather than add more places where this appear

Nightly is needed if you want to check correctly the docs as in docs.rs
I added a NIGHTLY flag so the user can decide how to use it

Co-authored-by: BD103 <[email protected]>

Co-authored-by: François Mockers <[email protected]>

alice-i-cecile · 2024-04-08T14:57:22Z

@Brezak could I get your review here?

Brezak · 2024-04-08T15:23:51Z

.github/workflows/ci.yml

+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ env.NIGHTLY_TOOLCHAIN }}


Could you add a comment explaining why we need nightly. Something like:

Suggested change

- uses: dtolnay/rust-toolchain@master

with:

toolchain: ${{ env.NIGHTLY_TOOLCHAIN }}

# Use nightly so we can use `rustdoc-scrape-examples`. See rust-lang\rust#88791

- uses: dtolnay/rust-toolchain@master

with:

toolchain: ${{ env.NIGHTLY_TOOLCHAIN }}

@james7132

# Objective - Fixes #12905. ## Solution - Use proper code `` tags for `TaskPoolBuilder::thread_name`. - Remove leftover documentation in `TaskPool` referencing the deleted `TaskPoolInner` struct. - It may be possible to rephrase this, but I do not know enough about the task pool to write something. (cc @james7132 who made the change removing `TaskPoolInner`.) - Ignore a buggy rustdoc lint that thinks `App` is already in scope for `UpdateMode` doc. (Extracted from #12692.)

# Objective - I daily drive nightly Rust when developing Bevy, so I notice when new warnings are raised by `cargo check` and Clippy. - `cargo +nightly clippy` raises a few of these new warnings. ## Solution - Fix most warnings from `cargo +nightly clippy` - I skipped the docs-related warnings because some were covered by #12692. - Use `Clone::clone_from` in applicable scenarios, which can sometimes avoid an extra allocation. - Implement `Default` for structs that have a `pub const fn new() -> Self` method. - Fix an occurrence where generic constraints were defined in both `<C: Trait>` and `where C: Trait`. - Removed generic constraints that were implied by the `Bundle` trait. --- ## Changelog - `BatchingStrategy`, `NonGenericTypeCell`, and `GenericTypeCell` now implement `Default`.

# Objective - Fix some doc warnings - Add doc-scrape-examples to all examples Moved from #12692 I run `cargo +nightly doc --workspace --all-features --no-deps -Zunstable-options -Zrustdoc-scrape-examples` <details> ``` warning: public documentation for `GzAssetLoaderError` links to private item `GzAssetLoader` --> examples/asset/asset_decompression.rs:24:47 | 24 | /// Possible errors that can be produced by [`GzAssetLoader`] | ^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: `bevy` (example "asset_decompression") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d.rs:3:15 | 3 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d") generated 1 warning warning: unresolved link to `WorldQuery` --> examples/ecs/custom_query_param.rs:1:49 | 1 | //! This example illustrates the usage of the [`WorldQuery`] derive macro, which allows | ^^^^^^^^^^ no item named `WorldQuery` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "custom_query_param") generated 1 warning warning: unresolved link to `shape::Quad` --> examples/2d/mesh2d_vertex_color_texture.rs:4:15 | 4 | //! [`Quad`]: shape::Quad | ^^^^^^^^^^^ no item named `shape` in scope | = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: `bevy` (example "mesh2d_vertex_color_texture") generated 1 warning warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:48:9 | 48 | /// * [`CoolText`]: a custom RON text format that supports dependencies and embedded dependencies | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `TextPlugin` links to private item `Text` --> examples/asset/processing/asset_processing.rs:49:9 | 49 | /// * [`Text`]: a "normal" plain text file | ^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `TextPlugin` links to private item `CoolText` --> examples/asset/processing/asset_processing.rs:51:57 | 51 | /// It also defines an asset processor that will load [`CoolText`], resolve embedded dependenc... | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: `bevy` (example "asset_processing") generated 3 warnings warning: public documentation for `CustomAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:20:47 | 20 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: public documentation for `BlobAssetLoaderError` links to private item `CustomAssetLoader` --> examples/asset/custom_asset.rs:61:47 | 61 | /// Possible errors that can be produced by [`CustomAssetLoader`] | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` ``` warning: `bevy` (example "mesh2d") generated 1 warning warning: public documentation for `log_layers_ecs` links to private item `update_subscriber` --> examples/app/log_layers_ecs.rs:6:18 | 6 | //! Inside the [`update_subscriber`] function we will create a [`mpsc::Sender`] and a [`mpsc::R... | ^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default warning: unresolved link to `AdvancedLayer` --> examples/app/log_layers_ecs.rs:7:72 | 7 | ... will go into the [`AdvancedLayer`] and the [`Receiver`](mpsc::Receiver) will | ^^^^^^^^^^^^^ no item named `AdvancedLayer` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:8:42 | 8 | //! go into a non-send resource called [`LogEvents`] (It has to be non-send because [`Receiver`... | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `transfer_log_events` --> examples/app/log_layers_ecs.rs:9:30 | 9 | //! From there we will use [`transfer_log_events`] to transfer log events from [`LogEvents`] to... | ^^^^^^^^^^^^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: unresolved link to `LogEvents` --> examples/app/log_layers_ecs.rs:9:82 | 9 | ...nsfer log events from [`LogEvents`] to an ECS event called [`LogEvent`]. | ^^^^^^^^^ no item named `LogEvents` in scope | = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:9:119 | 9 | ...nts`] to an ECS event called [`LogEvent`]. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` warning: public documentation for `log_layers_ecs` links to private item `LogEvent` --> examples/app/log_layers_ecs.rs:11:49 | 11 | //! Finally, after all that we can access the [`LogEvent`] event from our systems and use it. | ^^^^^^^^ this item is private | = note: this link will resolve properly if you pass `--document-private-items` ``` <details/>

alice-i-cecile requested a review from BD103 March 24, 2024 22:20

alice-i-cecile added C-Docs An addition or correction to our documentation A-Build-System Related to build systems or continuous integration labels Mar 25, 2024

alice-i-cecile approved these changes Mar 25, 2024

View reviewed changes

james7132 requested a review from mockersf March 25, 2024 01:06

BD103 suggested changes Mar 30, 2024

View reviewed changes

mockersf reviewed Mar 31, 2024

View reviewed changes

.github/workflows/ci.yml Outdated Show resolved Hide resolved

mockersf reviewed Mar 31, 2024

View reviewed changes

ameknite and others added 15 commits March 31, 2024 13:52

fix duplication of cfg_attr

bbc784c

Rectangle instead of Quad in Docs

c31fea7

remove pub in examples

c501e67

use QueryData instead of WorldQuery in docs

c47cf7a

add doc-scrape–examples

1e23f17

fix log_layers_ecs docs

4f5f7b9

allow redundant_explicit_links

378c431

Same docs settings, for ci and deployment

10ce4d0

return comment, deleted by mistake

2647b52

use nightly toolchain

153502c

separate ci, check doc and doc test individually

10d57f1

use stable toolchain in doc test ci

680d015

Update crates/bevy_winit/src/winit_config.rs

a4f4279

Co-authored-by: BD103 <[email protected]>

LCogEvents -> LogEvents

6c4e0cb

Co-authored-by: BD103 <[email protected]>

make items private

d145809

ameknite force-pushed the docs-ci branch from 149eaaf to d145809 Compare March 31, 2024 19:52

ameknite and others added 4 commits March 31, 2024 13:57

use explicit toolchain

0ad29ea

Co-authored-by: François Mockers <[email protected]>

change to only use nightly with --deploy-docs

476ec5f

always use --workspace

40a6ec9

use nightly flag

739d52e

BD103 mentioned this pull request Apr 8, 2024

Main branch fails to compile on Rust beta. #12905

Closed

alice-i-cecile requested a review from BD103 April 8, 2024 14:57

Brezak suggested changes Apr 8, 2024

View reviewed changes

BD103 mentioned this pull request Apr 9, 2024

Fix beta CI #12913

Merged

BD103 mentioned this pull request Apr 11, 2024

Fix some nightly Clippy lints #12927

Merged

ameknite mentioned this pull request Apr 14, 2024

Fix some doc warnings #12961

Merged

ameknite closed this May 29, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use same docs, for CI and deployment #12692

Use same docs, for CI and deployment #12692

ameknite commented Mar 24, 2024 •

edited

Loading

BD103 left a comment

BD103 Mar 30, 2024

ameknite Mar 31, 2024

BD103 Mar 31, 2024

mockersf Mar 31, 2024 •

edited

Loading

ameknite Mar 31, 2024 •

edited

Loading

alice-i-cecile commented Apr 8, 2024

Brezak Apr 8, 2024

Use same docs, for CI and deployment #12692

Use same docs, for CI and deployment #12692

Conversation

ameknite commented Mar 24, 2024 • edited Loading

Objective

Solution

BD103 left a comment

Choose a reason for hiding this comment

BD103 Mar 30, 2024

Choose a reason for hiding this comment

ameknite Mar 31, 2024

Choose a reason for hiding this comment

BD103 Mar 31, 2024

Choose a reason for hiding this comment

mockersf Mar 31, 2024 • edited Loading

Choose a reason for hiding this comment

ameknite Mar 31, 2024 • edited Loading

Choose a reason for hiding this comment

alice-i-cecile commented Apr 8, 2024

Brezak Apr 8, 2024

Choose a reason for hiding this comment

ameknite commented Mar 24, 2024 •

edited

Loading

mockersf Mar 31, 2024 •

edited

Loading

ameknite Mar 31, 2024 •

edited

Loading