Add a link to migrating docs to home (#1389)

### What
Add a link to migrating docs to the home page in the docs, and update
other parts of the home page docs.

<img width="738" alt="Screenshot 2024-11-06 at 10 47 05 PM"
src="https://github.com/user-attachments/assets/77176926-385d-419a-ae24-c229a6ca35e9">


### Why
So that the migrating docs are easily discovered by anyone browsing the
Rust docs. To make it current.

Makefile

@@ -27,7 +27,7 @@ build-fuzz:
 
 readme:
 	cd soroban-sdk \
-		&& cargo +nightly rustdoc -- -Zunstable-options -wjson \
+		&& cargo +nightly rustdoc --features testutils -- -Zunstable-options -wjson \
 		&& cat ../target/doc/soroban_sdk.json \
 		| jq -r '.index[.root|tostring].docs' \
 		> README.md

soroban-sdk/README.md

@@ -1,20 +1,28 @@
-Soroban SDK supports writing programs for the Soroban smart contract
-platform.
+Soroban SDK supports writing smart contracts for the Wasm-powered [Soroban] smart contract
+runtime, deployed on [Stellar].
 
 ### Docs
 
-See [soroban.stellar.org](https://soroban.stellar.org) for documentation.
+See [developers.stellar.org] for documentation about building smart contracts for [Stellar].
+
+[developers.stellar.org]: https://developers.stellar.org
+[Stellar]: https://stellar.org
+[Soroban]: https://stellar.org/soroban
+
+### Migrating Major Versions
+
+See [_migrating] for a summary of how to migrate from one major version to another.
 
 ### Examples
 
 ```rust
 use soroban_sdk::{contract, contractimpl, vec, symbol_short, BytesN, Env, Symbol, Vec};
 
 #[contract]
-pub struct HelloContract;
+pub struct Contract;
 
 #[contractimpl]
-impl HelloContract {
+impl Contract {
     pub fn hello(env: Env, to: Symbol) -> Vec<Symbol> {
         vec![&env, symbol_short!("Hello"), to]
     }
@@ -26,8 +34,8 @@ fn test() {
 # #[cfg(feature = "testutils")]
 # fn main() {
     let env = Env::default();
-    let contract_id = env.register(HelloContract, ());
-    let client = HelloContractClient::new(&env, &contract_id);
+    let contract_id = env.register(Contract, ());
+    let client = ContractClient::new(&env, &contract_id);
 
     let words = client.hello(&symbol_short!("Dev"));
 
@@ -37,5 +45,6 @@ fn test() {
 # fn main() { }
 ```
 
-More examples are available at <https://soroban.stellar.org/docs/category/basic-tutorials>
-and <https://soroban.stellar.org/docs/category/advanced-tutorials>.
+More examples are available at:
+- <https://developers.stellar.org/docs/build/smart-contracts/example-contracts>
+- <https://developers.stellar.org/docs/build/guides>

soroban-sdk/src/lib.rs

@@ -1,20 +1,28 @@
-//! Soroban SDK supports writing programs for the Soroban smart contract
-//! platform.
+//! Soroban SDK supports writing smart contracts for the Wasm-powered [Soroban] smart contract
+//! runtime, deployed on [Stellar].
 //!
 //! ### Docs
 //!
-//! See [soroban.stellar.org](https://soroban.stellar.org) for documentation.
+//! See [developers.stellar.org] for documentation about building smart contracts for [Stellar].
+//!
+//! [developers.stellar.org]: https://developers.stellar.org
+//! [Stellar]: https://stellar.org
+//! [Soroban]: https://stellar.org/soroban
+//!
+//! ### Migrating Major Versions
+//!
+//! See [_migrating] for a summary of how to migrate from one major version to another.
 //!
 //! ### Examples
 //!
 //! ```rust
 //! use soroban_sdk::{contract, contractimpl, vec, symbol_short, BytesN, Env, Symbol, Vec};
 //!
 //! #[contract]
-//! pub struct HelloContract;
+//! pub struct Contract;
 //!
 //! #[contractimpl]
-//! impl HelloContract {
+//! impl Contract {
 //!     pub fn hello(env: Env, to: Symbol) -> Vec<Symbol> {
 //!         vec![&env, symbol_short!("Hello"), to]
 //!     }
@@ -26,8 +34,8 @@
 //! # #[cfg(feature = "testutils")]
 //! # fn main() {
 //!     let env = Env::default();
-//!     let contract_id = env.register(HelloContract, ());
-//!     let client = HelloContractClient::new(&env, &contract_id);
+//!     let contract_id = env.register(Contract, ());
+//!     let client = ContractClient::new(&env, &contract_id);
 //!
 //!     let words = client.hello(&symbol_short!("Dev"));
 //!
@@ -37,8 +45,9 @@
 //! # fn main() { }
 //! ```
 //!
-//! More examples are available at <https://soroban.stellar.org/docs/category/basic-tutorials>
-//! and <https://soroban.stellar.org/docs/category/advanced-tutorials>.
+//! More examples are available at:
+//! - <https://developers.stellar.org/docs/build/smart-contracts/example-contracts>
+//! - <https://developers.stellar.org/docs/build/guides>
 
 #![cfg_attr(target_family = "wasm", no_std)]
 #![cfg_attr(feature = "docs", feature(doc_cfg))]