change(doc): Refactor user & dev docs (#8145)

* Fix the rendering of expandable content

* Refactor the docs refs in the readme

* Change the search query for docs.rs

* Refactor the landing docs for the `zebrad` crate

* List Zebra crates in the landing docs for `zebrad`

* Remove `## Future Work` from the main readme

This section doesn't say anything useful.

---------

Co-authored-by: Arya <aryasolhi@gmail.com>

README.md

@@ -72,9 +72,11 @@ Every few weeks, we release a [new Zebra version](https://github.com/ZcashFounda
 
 Below are quick summaries for installing the dependencies on your machine.
 
-<details>
+[//]: # "The empty line in the `summary` tag below is required for correct Markdown rendering."
+<details><summary>
 
-<summary><h4>General instructions for installing dependencies</h4></summary>
+#### General instructions for installing dependencies
+</summary>
 
 1. Install [`cargo` and `rustc`](https://www.rust-lang.org/tools/install).
 
@@ -88,9 +90,11 @@ Below are quick summaries for installing the dependencies on your machine.
 
 </details>
 
-<details>
+[//]: # "The empty line in the `summary` tag below is required for correct Markdown rendering."
+<details><summary>
 
-<summary><h4>Dependencies on Arch</h4></summary>
+#### Dependencies on Arch
+</summary>
 
 ```sh
 sudo pacman -S rust clang pkgconf
@@ -178,20 +182,20 @@ There are a few bugs in Zebra that we're still working on fixing:
 
 - Experimental Tor support is disabled until [Zebra upgrades to the latest `arti-client`](https://github.com/ZcashFoundation/zebra/issues/5492). This happened due to a Rust dependency conflict, which could only be resolved by `arti` upgrading to a version of `x25519-dalek` with the dependency fix.
 
-## Future Work
-
-We will continue to add new features as part of future network upgrades, and in response to community feedback.
-
 ## Documentation
 
-The [Zebra website](https://zebra.zfnd.org/) contains user documentation, such
+The Zcash Foundation maintains the following resources documenting Zebra:
-as how to run or configure Zebra, set up metrics integrations, etc., as well as
-developer documentation, such as design documents. It also renders
-[internal documentation](https://doc-internal.zebra.zfnd.org) for private APIs
-on the `main` branch.
 
-`docs.rs` renders [API documentation](https://docs.rs/releases/search?query=zebra)
+- The Zebra Book:
-for the external API of the latest releases of our crates.
+  - [General Introduction](https://zebra.zfnd.org/index.html),
+  - [User Documentation](https://zebra.zfnd.org/user.html),
+  - [Developer Documentation](https://zebra.zfnd.org/dev.html).
+
+- The public APIs for the latest releases of the individual `zebra-*` crates are documented at
+[docs.rs](https://docs.rs/releases/search?query=zebrad).
+
+- The internal APIs for the `main` branch are documented at
+<https://doc-internal.zebra.zfnd.org>.
 
 ## User support
 

book/src/api.md

@@ -2,7 +2,7 @@
 
 Zebra's API documentation is generated using Rustdoc:
 
-- [`docs.rs`](https://docs.rs/releases/search?query=zebra) renders documentation for the public API
+- [`docs.rs`](https://docs.rs/releases/search?query=zebrad) renders documentation for the public API
   of the latest crate releases;
 - [`doc-internal.zebra.zfnd.org`](https://doc-internal.zebra.zfnd.org/) renders documentation for
   the internal API on the `main` branch.

book/src/dev.md

@@ -3,7 +3,7 @@
 This section contains the contribution guide and design documentation. It
 does not contain API documentation, which is generated using Rustdoc:
 
-- [`docs.rs`](https://docs.rs/releases/search?query=zebra) renders documentation for the public API
+- [`docs.rs`](https://docs.rs/releases/search?query=zebrad) renders documentation for the public API
   of the latest crate releases;
 - [`doc-internal.zebra.zfnd.org`](https://doc-internal.zebra.zfnd.org/) renders documentation for
   the internal API on the `main` branch.

book/theme/css/custom.css

@@ -13,3 +13,11 @@ html.ayu #service-dep-diagram,
 html.coal #service-dep-diagram {
     filter: invert(1);
 }
+
+h2,
+h3,
+h4,
+h5,
+h6 {
+  display: inline-block;
+}

zebrad/src/lib.rs

@@ -1,16 +1,7 @@
 //! ![Zebra logotype](https://zfnd.org/wp-content/uploads/2022/03/zebra-logotype.png)
 //!
-//! Zebra is a Zcash node written in Rust.
+//! Zebra is a Zcash full node written in Rust. Follow the [introductory
-//!
+//! page](https://zebra.zfnd.org/index.html#documentation) in the Zebra Book to learn more.
-//! The `zebrad` binary uses a collection of `zebra-*` crates,
-//! which implement the different components of a Zcash node
-//! (networking, chain structures, validation, rpc, etc).
-//!
-//! [Rendered docs for the latest crate releases](https://docs.rs/releases/search?query=zebra).
-//!
-//! [Rendered docs from the `main` branch](https://doc-internal.zebra.zfnd.org).
-//!
-//! [Join us on the Zcash Foundation Engineering Discord](https://discord.gg/na6QZNd).
 //!
 //! ## About Zcash
 //!
@@ -66,7 +57,9 @@
 //!
 //! ## Zebra Feature Flags
 //!
-//! The following `zebrad` feature flags are available at compile time:
+//! The following [Cargo
+//! features](https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options)
+//! are available at compile time:
 //!
 //! ### JSON-RPC
 //!
@@ -117,6 +110,29 @@
 //! * `internal-miner`: enable experimental support for mining inside Zebra, without an external
 //!   mining pool. This feature is only supported on testnet. Use a GPU or ASIC on mainnet for
 //!   efficient mining.
+//!
+//! ## Zebra crates
+//!
+//! [The Zebra monorepo](https://github.com/ZcashFoundation/zebra) is a collection of the following
+//! crates:
+//!
+//! - [tower-batch-control](https://docs.rs/tower-batch-control/latest/tower_batch_control/)
+//! - [tower-fallback](https://docs.rs/tower-fallback/latest/tower_fallback/)
+//! - [zebra-chain](https://docs.rs/zebra-chain/latest/zebra_chain/)
+//! - [zebra-consensus](https://docs.rs/zebra-consensus/latest/zebra_consensus/)
+//! - [zebra-network](https://docs.rs/zebra-network/latest/zebra_network/)
+//! - [zebra-node-services](https://docs.rs/zebra-node-services/latest/zebra_node_services/)
+//! - [zebra-rpc](https://docs.rs/zebra-rpc/latest/zebra_rpc/)
+//! - [zebra-scan](https://docs.rs/zebra-scan/latest/zebra_scan/)
+//! - [zebra-script](https://docs.rs/zebra-script/latest/zebra_script/)
+//! - [zebra-state](https://docs.rs/zebra-state/latest/zebra_state/)
+//! - [zebra-test](https://docs.rs/zebra-test/latest/zebra_test/)
+//! - [zebra-utils](https://docs.rs/zebra-utils/latest/zebra_utils/)
+//! - [zebrad](https://docs.rs/zebrad/latest/zebrad/)
+//!
+//! The links in the list above point to the documentation of the public APIs of the crates. For
+//! the documentation of the internal APIs, follow <https://doc-internal.zebra.zfnd.org> that lists
+//! all Zebra crates as well in the left sidebar.
 
 #![doc(html_favicon_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-favicon-128.png")]
 #![doc(html_logo_url = "https://zfnd.org/wp-content/uploads/2022/03/zebra-icon.png")]