Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 7 commits into from
Jan 12, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
62b8b2a
Fix the rendering of expandable content
upbqdn Jan 9, 2024
aad3229
Refactor the docs refs in the readme
upbqdn Jan 9, 2024
662ac0e
Change the search query for docs.rs
upbqdn Jan 9, 2024
ce21a91
Refactor the landing docs for the `zebrad` crate
upbqdn Jan 9, 2024
9052127
List Zebra crates in the landing docs for `zebrad`
upbqdn Jan 9, 2024
2e752b8
Remove `## Future Work` from the main readme
upbqdn Jan 9, 2024
30ff137
Merge branch 'main' into link-crates-docs
arya2 Jan 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 18 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand All @@ -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
Expand Down Expand Up @@ -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
## Documentation

We will continue to add new features as part of future network upgrades, and in response to community feedback.
The Zcash Foundation maintains the following resources documenting Zebra:

## Documentation
- 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 [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 public APIs for the latest releases of the individual `zebra-*` crates are documented at
[docs.rs](https://docs.rs/releases/search?query=zebrad).

`docs.rs` renders [API documentation](https://docs.rs/releases/search?query=zebra)
for the external API of the latest releases of our crates.
- The internal APIs for the `main` branch are documented at
<https://doc-internal.zebra.zfnd.org>.

## User support

Expand Down
2 changes: 1 addition & 1 deletion book/src/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 1 addition & 1 deletion book/src/dev.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 9 additions & 1 deletion book/theme/css/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 28 additions & 12 deletions zebrad/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
//!
Expand Down Expand Up @@ -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
//!
Expand Down Expand Up @@ -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")]
Expand Down
Loading