zecfoundation
/
zebra
mirror of https://github.com/ZcashFoundation/zebra.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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>
This commit is contained in:
Marek 2024-01-12 23:36:04 +01:00 committed by GitHub
parent 54c702e73c
commit 01fa50cba3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 58 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
README.md
View File

@ -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
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.
The Zcash Foundation maintains the following resources documenting Zebra:
`docs.rs` renders [API documentation](https://docs.rs/releases/search?query=zebra)
for the external API of the latest releases of our crates.
- The Zebra Book:
- [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

2
book/src/api.md
View File

@ -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.

2
book/src/dev.md
View File

@ -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.

10
book/theme/css/custom.css
View File

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

40
zebrad/src/lib.rs
View File

@ -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.
//!
//! 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).
//! 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.
//!
//! ## 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")]