diff --git a/.github/contributing/docs_guide.md b/.github/contributing/docs_guide.md new file mode 100644 index 0000000000000..6019de58a7437 --- /dev/null +++ b/.github/contributing/docs_guide.md @@ -0,0 +1,57 @@ +# Documentations Guide + +This guide aims to ensure consistency in the Bevy crates documentation, they should be seen as advice and not strict rules and should therefore be adapted on a case-by-case basis. + +## The crate documentation + +1. The first line is a single sentence that summarizes the crate role in the Bevy ecosystem. +2. The first line is followed by an empty line. +3. The documentation may contain more details. +4. Links are usually placed at the end, depending on context (inline links may be useful clarification in a longer documentation block). +5. The crate attributes (`#![attribute]`) are placed _before_ the documentation. Consumers of the documentation are more likely to visit generated docs, rather than reading them in the source files. + +The format of the documentation will depend on the kind of the crate. + +- If the crate adds functionalities to Bevy (e.g. `bevy_time`, `bevy_input`, etc.) the documentation takes this format : + +```rust +//! functionality for the [Bevy game engine]. +//! +//! +//! +//! [Bevy game engine]: https://bevyengine.org/ +``` + +Example for `bevy_input` + +```rust +//! Input functionality for the [Bevy game engine]. +//! +//! # Supported input devices +//! +//! Bevy currently supports keyboard, mouse, gamepad, and touch inputs. +//! +//! [Bevy game engine]: https://bevyengine.org/ +``` + +- If the crate adapts an external crate for Bevy (e.g. `bevy_winit`, `bevy_gilrs`, etc.) the documentation takes this format : + +**Note**: the link to the external crates documentation should point to the version used by the bevy crate and not the latest version. + +```rust +//! Integration of the [`XXX`] crate to the [Bevy game engine]. +//! +//! +//! +//! [`XXX`]: +//! [Bevy game engine]: https://bevyengine.org/ +``` + +Example for `bevy_gilrs` + +```rust +//! Integration of the [`gilrs`] crate to the [Bevy game engine]. +//! +//! [`gilrs`]: https://docs.rs/gilrs/0.10.1/gilrs/ +//! [Bevy game engine]: https://bevyengine.org/ +```