From afaa359b0d7e31ae74c997594cbdb7fd57e3546b Mon Sep 17 00:00:00 2001 From: Greg Fitzgerald Date: Thu, 23 Jan 2020 21:21:43 -0700 Subject: [PATCH] Reorg the book (#7952) * Move application-oriented docs * Reorg the book * Fix build * Apply review feedback * verb-noun --- book/build-cli-usage.sh | 4 +- book/src/SUMMARY.md | 82 +++++++++---------- book/src/api-reference/README.md | 4 - book/src/{programs => apps}/README.md | 2 +- book/src/{programs => apps}/drones.md | 0 .../{api-reference => apps}/javascript-api.md | 0 .../{api-reference => apps}/jsonrpc-api.md | 0 book/src/{programs => apps}/tictactoe.md | 0 .../{getting-started => apps}/webwallet.md | 0 .../README.md => building-from-source.md} | 2 +- .../.cli.md.header => cli/.usage.md.header} | 0 book/src/cli/README.md | 5 ++ .../{api-reference/cli.md => cli/usage.md} | 0 13 files changed, 50 insertions(+), 49 deletions(-) delete mode 100644 book/src/api-reference/README.md rename book/src/{programs => apps}/README.md (91%) rename book/src/{programs => apps}/drones.md (100%) rename book/src/{api-reference => apps}/javascript-api.md (100%) rename book/src/{api-reference => apps}/jsonrpc-api.md (100%) rename book/src/{programs => apps}/tictactoe.md (100%) rename book/src/{getting-started => apps}/webwallet.md (100%) rename book/src/{getting-started/README.md => building-from-source.md} (99%) rename book/src/{api-reference/.cli.md.header => cli/.usage.md.header} (100%) create mode 100644 book/src/cli/README.md rename book/src/{api-reference/cli.md => cli/usage.md} (100%) diff --git a/book/build-cli-usage.sh b/book/build-cli-usage.sh index f46a5e36c..8dd353401 100755 --- a/book/build-cli-usage.sh +++ b/book/build-cli-usage.sh @@ -5,9 +5,9 @@ cd "$(dirname "$0")" usage=$(cargo -q run -p solana-cli -- -C ~/.foo --help | sed 's|'"$HOME"'|~|g') -out=${1:-src/api-reference/cli.md} +out=${1:-src/cli/usage.md} -cat src/api-reference/.cli.md.header > "$out" +cat src/cli/.usage.md.header > "$out" section() { declare mark=${2:-"###"} diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 1317d2a35..8d4dda51e 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,12 +1,31 @@ # Table of contents -* [The Solana Codebase](introduction.md) -* [Building from Source](getting-started/README.md) - * [Example Client: Web Wallet](getting-started/webwallet.md) -* [Programming Model](programs/README.md) - * [Example: Tic-Tac-Toe](programs/tictactoe.md) - * [Drones](programs/drones.md) -* [A Solana Cluster](cluster/README.md) +* [Introduction](introduction.md) +* [Using Solana from the Command-line](cli/README.md) + * [Command-line Usage](cli/usage.md) + * [Paper Wallet](paper-wallet/README.md) + * [Installation](paper-wallet/installation.md) + * [Paper Wallet Usage](paper-wallet/usage.md) + * [Offline Signing](offline-signing/README.md) + * [Durable Transaction Nonces](offline-signing/durable-nonce.md) +* [Developing Applications](apps/README.md) + * [Example: Web Wallet](apps/webwallet.md) + * [Example: Tic-Tac-Toe](apps/tictactoe.md) + * [Drones](apps/drones.md) + * [Anatomy of a Transaction](transaction.md) + * [JSON RPC API](apps/jsonrpc-api.md) + * [JavaScript API](apps/javascript-api.md) +* [Running a Validator](running-validator/README.md) + * [Validator Requirements](running-validator/validator-reqs.md) + * [Choosing a Testnet](running-validator/validator-testnet.md) + * [Installing the Validator Software](running-validator/validator-software.md) + * [Starting a Validator](running-validator/validator-start.md) + * [Staking](running-validator/validator-stake.md) + * [Monitoring a Validator](running-validator/validator-monitor.md) + * [Publishing Validator Info](running-validator/validator-info.md) + * [Troubleshooting](running-validator/validator-troubleshoot.md) +* [Running an Archiver](running-archiver.md) +* [Understanding Solana's Architecture](cluster/README.md) * [Synchronization](cluster/synchronization.md) * [Leader Rotation](cluster/leader-rotation.md) * [Fork Generation](cluster/fork-generation.md) @@ -22,41 +41,8 @@ * [Blockstore](validator/blockstore.md) * [Gossip Service](validator/gossip.md) * [The Runtime](validator/runtime.md) -* [Anatomy of a Transaction](transaction.md) -* [Running a Validator](running-validator/README.md) - * [Validator Requirements](running-validator/validator-reqs.md) - * [Choosing a Testnet](running-validator/validator-testnet.md) - * [Installing the Validator Software](running-validator/validator-software.md) - * [Starting a Validator](running-validator/validator-start.md) - * [Staking](running-validator/validator-stake.md) - * [Monitoring a Validator](running-validator/validator-monitor.md) - * [Publishing Validator Info](running-validator/validator-info.md) - * [Troubleshooting](running-validator/validator-troubleshoot.md) -* [Running an Archiver](running-archiver.md) -* [Paper Wallet](paper-wallet/README.md) - * [Installation](paper-wallet/installation.md) - * [Paper Wallet Usage](paper-wallet/usage.md) -* [Offline Signing](offline-signing/README.md) - * [Durable Transaction Nonces](offline-signing/durable-nonce.md) -* [API Reference](api-reference/README.md) - * [JSON RPC API](api-reference/jsonrpc-api.md) - * [JavaScript API](api-reference/javascript-api.md) - * [solana CLI](api-reference/cli.md) +* [Building from Source](building-from-source.md) * [Terminology](terminology.md) -* [Accepted Design Proposals](proposals/README.md) - * [Ledger Replication](proposals/ledger-replication-to-implement.md) - * [Secure Vote Signing](proposals/vote-signing-to-implement.md) - * [Cluster Test Framework](proposals/cluster-test-framework.md) - * [Validator](proposals/validator-proposal.md) - * [Simple Payment and State Verification](proposals/simple-payment-and-state-verification.md) - * [Cross-Program Invocation](proposals/cross-program-invocation.md) - * [Inter-chain Transaction Verification](proposals/interchain-transaction-verification.md) - * [Snapshot Verification](proposals/snapshot-verification.md) - * [Bankless Leader](proposals/bankless-leader.md) - * [Slashing](proposals/slashing.md) - * [Tick Verification](proposals/tick-verification.md) - * [Block Confirmation](proposals/block-confirmation.md) - * [ABI Management](proposals/abi-management.md) * [Implemented Design Proposals](implemented-proposals/README.md) * [Cluster Software Installation and Updates](implemented-proposals/installer.md) * [Cluster Economics](implemented-proposals/ed_overview/README.md) @@ -89,3 +75,17 @@ * [Validator Timestamp Oracle](implemented-proposals/validator-timestamp-oracle.md) * [Commitment](implemented-proposals/commitment.md) * [Snapshot Verification](implemented-proposals/snapshot-verification.md) +* [Accepted Design Proposals](proposals/README.md) + * [Ledger Replication](proposals/ledger-replication-to-implement.md) + * [Secure Vote Signing](proposals/vote-signing-to-implement.md) + * [Cluster Test Framework](proposals/cluster-test-framework.md) + * [Validator](proposals/validator-proposal.md) + * [Simple Payment and State Verification](proposals/simple-payment-and-state-verification.md) + * [Cross-Program Invocation](proposals/cross-program-invocation.md) + * [Inter-chain Transaction Verification](proposals/interchain-transaction-verification.md) + * [Snapshot Verification](proposals/snapshot-verification.md) + * [Bankless Leader](proposals/bankless-leader.md) + * [Slashing](proposals/slashing.md) + * [Tick Verification](proposals/tick-verification.md) + * [Block Confirmation](proposals/block-confirmation.md) + * [ABI Management](proposals/abi-management.md) diff --git a/book/src/api-reference/README.md b/book/src/api-reference/README.md deleted file mode 100644 index 583cbd282..000000000 --- a/book/src/api-reference/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# API Reference - -The following sections contain API references material you may find useful when developing applications utilizing a Solana cluster. - diff --git a/book/src/programs/README.md b/book/src/apps/README.md similarity index 91% rename from book/src/programs/README.md rename to book/src/apps/README.md index f413890b9..878e3e6c0 100644 --- a/book/src/programs/README.md +++ b/book/src/apps/README.md @@ -1,6 +1,6 @@ # Programming Model -A client _app_ interacts with a Solana cluster by sending it _transactions_ with one or more _instructions_. The Solana _runtime_ passes those instructions to user-contributed _programs_. An instruction might, for example, tell a program to transfer _lamports_ from one _account_ to another or create an interactive contract that governs how lamports are transfered. Instructions are executed sequentially and atomically. If any instruction is invalid, any changes made within the transaction are discarded. +An _app_ interacts with a Solana cluster by sending it _transactions_ with one or more _instructions_. The Solana _runtime_ passes those instructions to user-contributed _programs_. An instruction might, for example, tell a program to transfer _lamports_ from one _account_ to another or create an interactive contract that governs how lamports are transfered. Instructions are executed sequentially and atomically. If any instruction is invalid, any changes made within the transaction are discarded. ### Accounts and Signatures diff --git a/book/src/programs/drones.md b/book/src/apps/drones.md similarity index 100% rename from book/src/programs/drones.md rename to book/src/apps/drones.md diff --git a/book/src/api-reference/javascript-api.md b/book/src/apps/javascript-api.md similarity index 100% rename from book/src/api-reference/javascript-api.md rename to book/src/apps/javascript-api.md diff --git a/book/src/api-reference/jsonrpc-api.md b/book/src/apps/jsonrpc-api.md similarity index 100% rename from book/src/api-reference/jsonrpc-api.md rename to book/src/apps/jsonrpc-api.md diff --git a/book/src/programs/tictactoe.md b/book/src/apps/tictactoe.md similarity index 100% rename from book/src/programs/tictactoe.md rename to book/src/apps/tictactoe.md diff --git a/book/src/getting-started/webwallet.md b/book/src/apps/webwallet.md similarity index 100% rename from book/src/getting-started/webwallet.md rename to book/src/apps/webwallet.md diff --git a/book/src/getting-started/README.md b/book/src/building-from-source.md similarity index 99% rename from book/src/getting-started/README.md rename to book/src/building-from-source.md index c8edc543d..00dc33c5a 100644 --- a/book/src/getting-started/README.md +++ b/book/src/building-from-source.md @@ -1,4 +1,4 @@ -# Getting Started +# Building from Source The Solana git repository contains all the scripts you might need to spin up your own local testnet. Depending on what you're looking to achieve, you may want to run a different variation, as the full-fledged, performance-enhanced multinode testnet is considerably more complex to set up than a Rust-only, singlenode testnode. If you are looking to develop high-level features, such as experimenting with smart contracts, save yourself some setup headaches and stick to the Rust-only singlenode demo. If you're doing performance optimization of the transaction pipeline, consider the enhanced singlenode demo. If you're doing consensus work, you'll need at least a Rust-only multinode demo. If you want to reproduce our TPS metrics, run the enhanced multinode demo. diff --git a/book/src/api-reference/.cli.md.header b/book/src/cli/.usage.md.header similarity index 100% rename from book/src/api-reference/.cli.md.header rename to book/src/cli/.usage.md.header diff --git a/book/src/cli/README.md b/book/src/cli/README.md new file mode 100644 index 000000000..6d0fc682f --- /dev/null +++ b/book/src/cli/README.md @@ -0,0 +1,5 @@ +# Using Solana from the Command-line + +This chapter describes the command-line tools for interacting with Solana. One +could use these tools to send payments, stake validators, and check account +balances. diff --git a/book/src/api-reference/cli.md b/book/src/cli/usage.md similarity index 100% rename from book/src/api-reference/cli.md rename to book/src/cli/usage.md