From f3346a80b9d1b7535f2c5256603b9b0e2340578c Mon Sep 17 00:00:00 2001
From: Jesse Braham <jessebraham@users.noreply.github.com>
Date: Wed, 13 Nov 2024 23:32:10 -0800
Subject: [PATCH] Update documentation to recommend `esp-generate` instead of
 `esp-template` (#2535)

* Update documentation to recommend `esp-generate` instead of `esp-template`

* Hide the `trm_link` macro in the documentation
---
 esp-hal/src/lib.rs             | 11 ++++++-----
 esp-hal/src/soc/esp32/mod.rs   |  1 +
 esp-hal/src/soc/esp32c2/mod.rs |  1 +
 esp-hal/src/soc/esp32c3/mod.rs |  1 +
 esp-hal/src/soc/esp32c6/mod.rs |  1 +
 esp-hal/src/soc/esp32h2/mod.rs |  1 +
 esp-hal/src/soc/esp32s2/mod.rs |  1 +
 esp-hal/src/soc/esp32s3/mod.rs |  1 +
 8 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/esp-hal/src/lib.rs b/esp-hal/src/lib.rs
index 2214852fe..8e17996eb 100644
--- a/esp-hal/src/lib.rs
+++ b/esp-hal/src/lib.rs
@@ -45,11 +45,13 @@
 //! before proceeding. We also have a [training] that covers some common
 //! scenarios with examples.
 //!
-//! We have a template for quick starting bare-metal projects, [esp-template].
-//! The template uses [cargo-generate], so ensure that it is installed and run:
+//! We have developed a project generation tool, [esp-generate], which we
+//! recommend when starting new projects. It can be installed and run, e.g.
+//! for the ESP32-C6, as follows:
 //!
 //! ```bash
-//! cargo generate -a esp-rs/esp-template
+//! cargo install esp-generate
+//! esp-generate --chip=esp32c6 your-project
 //! ```
 //!
 //! ## Blinky
@@ -128,8 +130,7 @@
 //! [embedded-hal]: https://github.com/rust-embedded/embedded-hal/tree/master/embedded-hal
 //! [embedded-hal-async]: https://github.com/rust-embedded/embedded-hal/tree/master/embedded-hal-async
 //! [xtask]: https://github.com/matklad/cargo-xtask
-//! [esp-template]: https://github.com/esp-rs/esp-template
-//! [cargo-generate]: https://github.com/cargo-generate/cargo-generate
+//! [esp-generate]: https://github.com/esp-rs/esp-generate
 //! [book]: https://docs.esp-rs.org/book/
 //! [training]: https://docs.esp-rs.org/no_std-training/
 //!
diff --git a/esp-hal/src/soc/esp32/mod.rs b/esp-hal/src/soc/esp32/mod.rs
index aeeffa81e..a4609a803 100644
--- a/esp-hal/src/soc/esp32/mod.rs
+++ b/esp-hal/src/soc/esp32/mod.rs
@@ -27,6 +27,7 @@ macro_rules! chip {
 }
 
 /// A link to the Technical Reference Manual (TRM) for the chip.
+#[doc(hidden)]
 #[macro_export]
 macro_rules! trm_link {
     () => { "https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf" };
diff --git a/esp-hal/src/soc/esp32c2/mod.rs b/esp-hal/src/soc/esp32c2/mod.rs
index da4a41fa4..93541428e 100644
--- a/esp-hal/src/soc/esp32c2/mod.rs
+++ b/esp-hal/src/soc/esp32c2/mod.rs
@@ -20,6 +20,7 @@ macro_rules! chip {
 }
 
 /// A link to the Technical Reference Manual (TRM) for the chip.
+#[doc(hidden)]
 #[macro_export]
 macro_rules! trm_link {
     () => { "https://www.espressif.com/sites/default/files/documentation/esp8684_technical_reference_manual_en.pdf" };
diff --git a/esp-hal/src/soc/esp32c3/mod.rs b/esp-hal/src/soc/esp32c3/mod.rs
index 6955b5c78..b8c5ae881 100644
--- a/esp-hal/src/soc/esp32c3/mod.rs
+++ b/esp-hal/src/soc/esp32c3/mod.rs
@@ -24,6 +24,7 @@ macro_rules! chip {
 }
 
 /// A link to the Technical Reference Manual (TRM) for the chip.
+#[doc(hidden)]
 #[macro_export]
 macro_rules! trm_link {
     () => { "https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf" };
diff --git a/esp-hal/src/soc/esp32c6/mod.rs b/esp-hal/src/soc/esp32c6/mod.rs
index 1ed7e74db..850407947 100644
--- a/esp-hal/src/soc/esp32c6/mod.rs
+++ b/esp-hal/src/soc/esp32c6/mod.rs
@@ -26,6 +26,7 @@ macro_rules! chip {
 }
 
 /// A link to the Technical Reference Manual (TRM) for the chip.
+#[doc(hidden)]
 #[macro_export]
 macro_rules! trm_link {
     () => { "https://www.espressif.com/sites/default/files/documentation/esp32-c6_technical_reference_manual_en.pdf" };
diff --git a/esp-hal/src/soc/esp32h2/mod.rs b/esp-hal/src/soc/esp32h2/mod.rs
index 9997f73fb..8eb9701de 100644
--- a/esp-hal/src/soc/esp32h2/mod.rs
+++ b/esp-hal/src/soc/esp32h2/mod.rs
@@ -25,6 +25,7 @@ macro_rules! chip {
 }
 
 /// A link to the Technical Reference Manual (TRM) for the chip.
+#[doc(hidden)]
 #[macro_export]
 macro_rules! trm_link {
     () => { "https://www.espressif.com/sites/default/files/documentation/esp32-h2_technical_reference_manual_en.pdf" };
diff --git a/esp-hal/src/soc/esp32s2/mod.rs b/esp-hal/src/soc/esp32s2/mod.rs
index ed39d3554..c6fdd8db1 100644
--- a/esp-hal/src/soc/esp32s2/mod.rs
+++ b/esp-hal/src/soc/esp32s2/mod.rs
@@ -32,6 +32,7 @@ macro_rules! chip {
 }
 
 /// A link to the Technical Reference Manual (TRM) for the chip.
+#[doc(hidden)]
 #[macro_export]
 macro_rules! trm_link {
     () => { "https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf" };
diff --git a/esp-hal/src/soc/esp32s3/mod.rs b/esp-hal/src/soc/esp32s3/mod.rs
index f0b5171c4..69189e2d4 100644
--- a/esp-hal/src/soc/esp32s3/mod.rs
+++ b/esp-hal/src/soc/esp32s3/mod.rs
@@ -33,6 +33,7 @@ macro_rules! chip {
 }
 
 /// A link to the Technical Reference Manual (TRM) for the chip.
+#[doc(hidden)]
 #[macro_export]
 macro_rules! trm_link {
     () => { "https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf" };