From bdf66387d698ec8bb9d2428666e20e35997d558e Mon Sep 17 00:00:00 2001 From: Henry de Valence Date: Thu, 6 Aug 2020 15:39:54 -0700 Subject: [PATCH] Reorganize the book. (#843) * Reorganize the book. This PR has one unfortunate change, which is that the README.md and CONTRIBUTING.md files in the book are symlinks to files in the parent directory. The motivation for this is to ensure that we don't maintain two copies of the same data, and that the landing page of the website matches the landing page of the Github repo, etc. However, I'm not sure whether these symlinks will work correctly on Windows. The alternatives are: - Duplicate the contents of the files and expect that people will know to keep them in sync; - Use relative links `../../README.md` in the `SUMMARY.md`. This seemed like it caused mdbook to dump the rendered files into the repository root rather than keeping them in the `book` directory. - Use a symlink (chosen option). This may not work on Windows but I think that the worst outcome would be that the book would be unbuildable unless someone used WSL or something. This seems like the least bad option. * Remove symlinks in favor of #include Turns out the symlinks aren't required! --- CONTRIBUTING.md | 18 +++++++++ README.md | 26 +++---------- book/src/CONTRIBUTING.md | 19 +--------- book/src/README.md | 1 + book/src/SUMMARY.md | 35 ++++++++---------- book/src/api.md | 6 +++ book/src/applications.md | 4 -- book/src/applications/utils.md | 1 - book/src/applications/zebrad.md | 8 ---- book/src/design_docs.md | 1 - book/src/dev.md | 7 ++++ book/src/{ => dev}/diagrams.md | 0 book/src/{ => dev}/diagrams/zebra-network.md | 0 .../{ => dev}/diagrams/zebra-network.monopic | Bin book/src/{ => dev}/overview.md | 2 +- book/src/dev/rfcs.md | 4 ++ .../{designs => dev/rfcs}/0000-template.md | 0 .../rfcs}/0001-pipelinable-block-lookup.md | 0 .../utils => dev}/zebra-checkpoints.md | 0 book/src/introduction.md | 11 ------ book/src/user.md | 1 + book/src/user/install.md | 13 +++++++ book/src/user/metrics.md | 22 +++++++++++ book/src/user/run.md | 21 +++++++++++ book/src/user/tracing.md | 21 +++++++++++ 25 files changed, 137 insertions(+), 84 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 book/src/README.md create mode 100644 book/src/api.md delete mode 100644 book/src/applications.md delete mode 100644 book/src/applications/utils.md delete mode 100644 book/src/applications/zebrad.md delete mode 100644 book/src/design_docs.md create mode 100644 book/src/dev.md rename book/src/{ => dev}/diagrams.md (100%) rename book/src/{ => dev}/diagrams/zebra-network.md (100%) rename book/src/{ => dev}/diagrams/zebra-network.monopic (100%) rename book/src/{ => dev}/overview.md (99%) create mode 100644 book/src/dev/rfcs.md rename book/src/{designs => dev/rfcs}/0000-template.md (100%) rename book/src/{designs => dev/rfcs}/0001-pipelinable-block-lookup.md (100%) rename book/src/{applications/utils => dev}/zebra-checkpoints.md (100%) delete mode 100644 book/src/introduction.md create mode 100644 book/src/user.md create mode 100644 book/src/user/install.md create mode 100644 book/src/user/metrics.md create mode 100644 book/src/user/run.md create mode 100644 book/src/user/tracing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4e5d408e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,18 @@ +# Contributing + +* [Bug Reports](#bug-reports) +* [Running and Debugging](#running-and-debugging) +* [Pull Requests](#pull-requests) +* [Writing Documentation](#writing-documentation) + +## Bug Reports +[bug-reports]: #bug-reports + +## Running and Debugging +[running-and-debugging]: #running-and-debugging + +## Pull Requests +[pull-requests]: #pull-requests + +## Writing Documentation +[writing-documentation]: #writing-documentation diff --git a/README.md b/README.md index e1703a0c..e3b50561 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,11 @@ libraries implementing the different components of a Zcash node (networking, chain structures, consensus rules, etc), and a `zebrad` binary which uses them. Most of our work so far has gone into `zebra-network`, building a new -networking stack for Zcash, and `zebra-chain`, building foundational data -structures. +networking stack for Zcash, `zebra-chain`, building foundational data +structures, `zebra-consensus`, implementing consensus rules, and +`zebra-state`, providing chain state. + +[Zebra Website](https://zebra.zfnd.org). [Rendered docs from the `main` branch](https://doc.zebra.zfnd.org). @@ -26,22 +29,3 @@ Zebra is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT). - -## Metrics - -Notes on local metrics collection: - -``` -# create a storage volume for grafana (once) -sudo docker volume create grafana-storage -# create a storage volume for prometheus (once) -sudo docker volume create prometheus-storage - -# run prometheus with the included config -sudo docker run --network host -v prometheus-storage:/prometheus -v /path/to/zebra/prometheus.yaml:/etc/prometheus/prometheus.yml prom/prometheus - -# run grafana -sudo docker run -d --network host -e GF_SERVER_HTTP_PORT=3030 -v grafana-storage:/var/lib/grafana grafana/grafana -``` - -Now the grafana dashboard is available at http://localhost:3030 ; the default password is admin/admin. diff --git a/book/src/CONTRIBUTING.md b/book/src/CONTRIBUTING.md index 4e5d408e..3ceed835 100644 --- a/book/src/CONTRIBUTING.md +++ b/book/src/CONTRIBUTING.md @@ -1,18 +1 @@ -# Contributing - -* [Bug Reports](#bug-reports) -* [Running and Debugging](#running-and-debugging) -* [Pull Requests](#pull-requests) -* [Writing Documentation](#writing-documentation) - -## Bug Reports -[bug-reports]: #bug-reports - -## Running and Debugging -[running-and-debugging]: #running-and-debugging - -## Pull Requests -[pull-requests]: #pull-requests - -## Writing Documentation -[writing-documentation]: #writing-documentation +{{#include ../../CONTRIBUTING.md}} \ No newline at end of file diff --git a/book/src/README.md b/book/src/README.md new file mode 100644 index 00000000..94fc2052 --- /dev/null +++ b/book/src/README.md @@ -0,0 +1 @@ +{{#include ../../README.md}} \ No newline at end of file diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 5ab3778d..e2e01e3c 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,21 +1,18 @@ # Summary -[Introduction](./introduction.md) -[Contribution Guide](./CONTRIBUTING.md) -[Design Overview](./overview.md) - -# Diagrams - -- [Diagrams](./diagrams.md) - - [Zebra Network](./diagrams/zebra-network.md) - -# Designs - -- [Design Documents](design_docs.md) - - [Pipelinable Block Lookup](./designs/0001-pipelinable-block-lookup.md) - -# Applications -- [Applications](applications.md) - - [zebrad](./applications/zebrad.md) - - [utils](./applications/utils.md) - - [zebra-checkpoints](./applications/utils/zebra-checkpoints.md) +[Zebra](README.md) +- [User Documentation](user.md) + - [Installing Zebra](user/install.md) + - [Running Zebra](user/run.md) + - [Tracing Zebra](user/tracing.md) + - [Zebra Metrics](user/metrics.md) +- [Developer Documentation](dev.md) + - [Contribution Guide](CONTRIBUTING.md) + - [Design Overview](dev/overview.md) + - [Zebra RFCs](dev/rfcs.md) + - [RFC Template](dev/rfcs/0000-template.md) + - [Pipelinable Block Lookup](dev/rfcs/0001-pipelinable-block-lookup.md) + - [Diagrams](dev/diagrams.md) + - [Network Architecture](dev/diagrams/zebra-network.md) + - [zebra-checkpoints](dev/zebra-checkpoints.md) +- [API Reference](api.md) diff --git a/book/src/api.md b/book/src/api.md new file mode 100644 index 00000000..c24898b8 --- /dev/null +++ b/book/src/api.md @@ -0,0 +1,6 @@ +# API Reference + +Zebra's API documentation is generated using Rustdoc: + +- [`doc.zebra.zfnd.org`](https://doc.zebra.zfnd.org/) renders documentation for the public API; +- [`doc-internal.zebra.zfnd.org`](https://doc-internal.zebra.zfnd.org/) renders documentation for the internal API. \ No newline at end of file diff --git a/book/src/applications.md b/book/src/applications.md deleted file mode 100644 index a217ca63..00000000 --- a/book/src/applications.md +++ /dev/null @@ -1,4 +0,0 @@ -# Applications - -- [zebrad](applications/zebrad.md) -- [zebra-checkpoints](applications/utils/zebra-checkpoints.md) diff --git a/book/src/applications/utils.md b/book/src/applications/utils.md deleted file mode 100644 index 06588bfb..00000000 --- a/book/src/applications/utils.md +++ /dev/null @@ -1 +0,0 @@ -# utils diff --git a/book/src/applications/zebrad.md b/book/src/applications/zebrad.md deleted file mode 100644 index 7f8d1574..00000000 --- a/book/src/applications/zebrad.md +++ /dev/null @@ -1,8 +0,0 @@ -# zebrad - -## Return Codes - -- 0 => Application exited successfully -- 1 => Application exited unsuccessfully -- 2 => Application crashed -- zebrad may also return platform-dependent codes diff --git a/book/src/design_docs.md b/book/src/design_docs.md deleted file mode 100644 index b24598c0..00000000 --- a/book/src/design_docs.md +++ /dev/null @@ -1 +0,0 @@ -# Design Documents diff --git a/book/src/dev.md b/book/src/dev.md new file mode 100644 index 00000000..f8d47cfe --- /dev/null +++ b/book/src/dev.md @@ -0,0 +1,7 @@ +# Developer Documentation + +- [Contribution Guide](CONTRIBUTING.md) +- [Design Overview](dev/overview.md) +- [Zebra RFCs](dev/rfcs.md) + 0. [RFC Template](dev/rfcs/0000-template.md) + 1. [Pipelinable Block Lookup](dev/rfcs/0001-pipelinable-block-lookup.md) \ No newline at end of file diff --git a/book/src/diagrams.md b/book/src/dev/diagrams.md similarity index 100% rename from book/src/diagrams.md rename to book/src/dev/diagrams.md diff --git a/book/src/diagrams/zebra-network.md b/book/src/dev/diagrams/zebra-network.md similarity index 100% rename from book/src/diagrams/zebra-network.md rename to book/src/dev/diagrams/zebra-network.md diff --git a/book/src/diagrams/zebra-network.monopic b/book/src/dev/diagrams/zebra-network.monopic similarity index 100% rename from book/src/diagrams/zebra-network.monopic rename to book/src/dev/diagrams/zebra-network.monopic diff --git a/book/src/overview.md b/book/src/dev/overview.md similarity index 99% rename from book/src/overview.md rename to book/src/dev/overview.md index 3e37954a..329effdd 100644 --- a/book/src/overview.md +++ b/book/src/dev/overview.md @@ -1,4 +1,4 @@ -Zebra Design Document +Design Overview --------------------- This document sketches the future design for Zebra. diff --git a/book/src/dev/rfcs.md b/book/src/dev/rfcs.md new file mode 100644 index 00000000..f1781eb7 --- /dev/null +++ b/book/src/dev/rfcs.md @@ -0,0 +1,4 @@ +# Zebra RFCs + +We are experimenting with using a process similar to the Rust RFC process to +document design decisions for Zebra. \ No newline at end of file diff --git a/book/src/designs/0000-template.md b/book/src/dev/rfcs/0000-template.md similarity index 100% rename from book/src/designs/0000-template.md rename to book/src/dev/rfcs/0000-template.md diff --git a/book/src/designs/0001-pipelinable-block-lookup.md b/book/src/dev/rfcs/0001-pipelinable-block-lookup.md similarity index 100% rename from book/src/designs/0001-pipelinable-block-lookup.md rename to book/src/dev/rfcs/0001-pipelinable-block-lookup.md diff --git a/book/src/applications/utils/zebra-checkpoints.md b/book/src/dev/zebra-checkpoints.md similarity index 100% rename from book/src/applications/utils/zebra-checkpoints.md rename to book/src/dev/zebra-checkpoints.md diff --git a/book/src/introduction.md b/book/src/introduction.md deleted file mode 100644 index 0c8621f9..00000000 --- a/book/src/introduction.md +++ /dev/null @@ -1,11 +0,0 @@ -# The Zebra Book - -Introduce the zebra project, explain what its for, high level concepts, how it differs from zcash, why it's being written. - -# Dev Guide - -Link to various chapters about how to contribute or work with the project, how to manipulate the log levels, how to set up the project, and the various dev practices we follow. - -# Design - -Introduce the overview and design documents. document how to propose a new design. \ No newline at end of file diff --git a/book/src/user.md b/book/src/user.md new file mode 100644 index 00000000..3a51d9a2 --- /dev/null +++ b/book/src/user.md @@ -0,0 +1 @@ +# User Documentation diff --git a/book/src/user/install.md b/book/src/user/install.md new file mode 100644 index 00000000..5ee1399f --- /dev/null +++ b/book/src/user/install.md @@ -0,0 +1,13 @@ +# Installing Zebra + +Zebra is still under development, so there is no supported packaging or +install mechanism. To run Zebra, check out the git repository: +``` +git clone https://github.com/ZcashFoundation/zebra +``` +and then run +``` +cargo build +``` + +Be aware that Zebra is still in an extremely early stage of development. \ No newline at end of file diff --git a/book/src/user/metrics.md b/book/src/user/metrics.md new file mode 100644 index 00000000..5fbece23 --- /dev/null +++ b/book/src/user/metrics.md @@ -0,0 +1,22 @@ +# Zebra Metrics + +Zebra has support for Prometheus, configured using the [`MetricsSection`][metrics_section]. + +This requires supporting infrastructure to collect and visualize metrics, for example: + +``` +# create a storage volume for grafana (once) +sudo docker volume create grafana-storage +# create a storage volume for prometheus (once) +sudo docker volume create prometheus-storage + +# run prometheus with the included config +sudo docker run --network host -v prometheus-storage:/prometheus -v /path/to/zebra/prometheus.yaml:/etc/prometheus/prometheus.yml prom/prometheus + +# run grafana +sudo docker run -d --network host -e GF_SERVER_HTTP_PORT=3030 -v grafana-storage:/var/lib/grafana grafana/grafana +``` + +Now the grafana dashboard is available at [http://localhost:3030](http://localhost:3030) ; the default username and password is `admin`/`admin`. + +[metrics_section]: https://doc.zebra.zfnd.org/zebrad/config/struct.MetricsSection.html diff --git a/book/src/user/run.md b/book/src/user/run.md new file mode 100644 index 00000000..b35dbd00 --- /dev/null +++ b/book/src/user/run.md @@ -0,0 +1,21 @@ +# Running Zebra + +`zebrad generate` generates a default config. These defaults will be used if +no config is present, so it's not necessary to generate a config. However, +having a config file with the default fields is a useful starting point for +changing the config. + +The configuration format is the TOML encoding of the internal config +structure, and documentation for all of the config options can be found +[here](https://doc.zebra.zfnd.org/zebrad/config/struct.ZebradConfig.html). + +* `zebrad start` starts a full node. +* `zebrad seed` starts a crawler that can power a DNS seeder, but does not + attempt to sync the chain state. + +## Return Codes + +- `0`: Application exited successfully +- `1`: Application exited unsuccessfully +- `2`: Application crashed +- `zebrad` may also return platform-dependent codes. \ No newline at end of file diff --git a/book/src/user/tracing.md b/book/src/user/tracing.md new file mode 100644 index 00000000..be3acf93 --- /dev/null +++ b/book/src/user/tracing.md @@ -0,0 +1,21 @@ +# Tracing Zebra + +Zebra supports dynamic tracing, configured using the config's +[`TracingSection`][tracing_section] and (optionally) an HTTP RPC endpoint. + +If the `endpoint_addr` is specified, `zebrad` will open an HTTP endpoint +allowing dynamic runtime configuration of the tracing filter. For instance, +if the config had `endpoint_addr = '127.0.0.1:3000'`, then + +* `curl -X GET localhost:3000/filter` retrieves the current filter string; +* `curl -X POST localhost:3000/filter -d "zebrad=trace"` sets the current filter string. + +See the [`filter`][filter] documentation for more details. + +Zebra also has support for generating [flamegraphs] of tracing spans, +configured using the [`flamegraph`][flamegraph] option. + +[tracing_section]: https://doc.zebra.zfnd.org/zebrad/config/struct.TracingSection.html +[filter]: https://doc.zebra.zfnd.org/zebrad/config/struct.TracingSection.html#structfield.filter +[flamegraph]: https://doc.zebra.zfnd.org/zebrad/config/struct.TracingSection.html#structfield.flamegraph +[flamegraphs]: http://www.brendangregg.com/flamegraphs.html