Add PAC readme, add banner directing to docs.embassy.dev.

Author: Dirbaio

stm32-metapac-gen/res/Cargo.toml

@@ -11,12 +11,14 @@ include = [
     "**/*.rs",
     "**/*.x",
     "Cargo.toml",
+    "README.md",
 ]
 
 [package.metadata.docs.rs]
 features = ["stm32h755zi-cm7", "pac", "metadata"]
 default-target = "thumbv7em-none-eabihf"
 targets = []
+rustdoc-args = ["--cfg", "docsrs"]
 
 [package.metadata.embassy_docs]
 features = ["pac", "metadata"]

stm32-metapac-gen/res/README.md

@@ -0,0 +1,44 @@
+# stm32-metapac
+
+This is a [Peripheral Access Crate](https://rust-embedded.github.io/book/start/registers.html) for STMicroelectronics STM32 microcontrollers.
+
+This crate has been automatically generated based on data in the [`stm32-data` project](https://github.com/embassy-rs/stm32-data), and is used for the [`embassy-stm32`](github.com/embassy-rs/embassy/) Rust Hardware Abstraction Layer (HAL) for the STM32 microcontrollers.
+
+## Metadata
+
+This PAC additionally exports "metadata" about the chips. To use it, enable the `metadata` feature and access it at `stm32_metapac::METADATA`. It is intended to be consumed from `build.rs` scripts or code-generation tools running on PCs, not from the firmware itself.
+
+The metadata includes the following info:
+
+- Memory maps for RAM, flash.
+- Interrupts
+- GPIO Alternate Function mappings
+- Interrupt -> peripheral mappings
+- DMA channel -> peripehral mappings
+- RCC clock tree information for each peripheral (what clocks does it receive, which RCC registers to poke to enable, reset, or choose the clock)
+
+## Supported chips
+
+This PAC aims to support all STM32 chip families:
+
+- STM32F0
+- STM32F1
+- STM32F2
+- STM32F3
+- STM32F4
+- STM32F7
+- STM32C0
+- STM32G0
+- STM32G4
+- STM32H5
+- STM32H7
+- STM32H7RS
+- STM32L0
+- STM32L1
+- STM32L4
+- STM32L5
+- STM32U0
+- STM32U5
+- STM32WB
+- STM32WBA
+- STM32WL

stm32-metapac-gen/res/src/lib.rs

@@ -3,6 +3,11 @@
 #![allow(unused)]
 #![allow(non_camel_case_types)]
 #![doc(html_no_source)]
+#![cfg_attr(
+    docsrs,
+    doc = "<div style='padding:30px;background:#810;color:#fff;text-align:center;'><p>You might want to <a href='https://docs.embassy.dev/stm32-metapac'>browse the `embassy-nrf` documentation on the Embassy website</a> instead.</p><p>The documentation here on `docs.rs` is built for a single chip only (stm32h755zi-cm7 in particular), while on the Embassy website you can pick your exact chip from the top menu. Available peripherals and their APIs change depending on the chip.</p></div>\n\n"
+)]
+#![doc = include_str!("../README.md")]
 
 pub mod common;
 

stm32-metapac-gen/src/lib.rs

@@ -336,6 +336,7 @@ impl Gen {
         }
 
         // copy misc files
+        fs::write(self.opts.out_dir.join("README.md"), include_bytes!("../res/README.md")).unwrap();
         fs::write(self.opts.out_dir.join("build.rs"), include_bytes!("../res/build.rs")).unwrap();
         fs::write(
             self.opts.out_dir.join("src/lib.rs"),