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!
This commit is contained in:
Henry de Valence
GitHub
parent
3d46ab746a
commit
bdf66387d6
|
|
@ -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
|
||||
26
README.md
26
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.
|
||||
|
|
|
|||
|
|
@ -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}}
|
||||
|
|
@ -0,0 +1 @@
|
|||
{{#include ../../README.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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
# Applications
|
||||
|
||||
- [zebrad](applications/zebrad.md)
|
||||
- [zebra-checkpoints](applications/utils/zebra-checkpoints.md)
|
||||
|
|
@ -1 +0,0 @@
|
|||
# utils
|
||||
|
|
@ -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
|
||||
|
|
@ -1 +0,0 @@
|
|||
# Design Documents
|
||||
|
|
@ -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)
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
Zebra Design Document
|
||||
Design Overview
|
||||
---------------------
|
||||
|
||||
This document sketches the future design for Zebra.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1 @@
|
|||
# User Documentation
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue