From 4fe990636131274846a118bbe9812bfbcb6b1194 Mon Sep 17 00:00:00 2001 From: Zach Date: Mon, 17 Sep 2018 12:43:10 -0400 Subject: [PATCH] docs: Update README (#2393) * update DOCS_README * add spec to docs & other lil fixes (#2402) --- docs/DOCS_README.md | 76 ++++++++++++++----- docs/README.md | 40 ++++++---- docs/config.js | 49 ++++++++++-- .../fast-sync.md | 0 4 files changed, 127 insertions(+), 38 deletions(-) rename docs/{networks => tendermint-core}/fast-sync.md (100%) diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md index 01ec07ad9..0d1e3f979 100644 --- a/docs/DOCS_README.md +++ b/docs/DOCS_README.md @@ -1,31 +1,69 @@ -# Documentation Maintenance Overview +# Docs Build Workflow -The documentation found in this directory is hosted at: +The documentation for Tendermint Core is hosted at: -- https://tendermint.com/docs/ +- https://tendermint.com/docs/ and +- https://tendermint-staging.interblock.io/docs/ -and built using [VuePress](https://vuepress.vuejs.org/) like below: +built from the files in this (`/docs`) directory for +[master](https://github.com/tendermint/tendermint/tree/master/docs) +and [develop](https://github.com/tendermint/tendermint/tree/develop/docs), +respectively. -```bash -npm install -g vuepress # global install vuepress tool, only once -npm install +## How It Works -mkdir -p .vuepress && cp config.js .vuepress/ -vuepress build -``` +There is a Jenkins job listening for changes in the `/docs` directory, on both +the `master` and `develop` branches. Any updates to files in this directory +on those branches will automatically trigger a website deployment. Under the hood, +a private website repository has make targets consumed by a standard Jenkins task. -Under the hood, Jenkins listens for changes (on develop or master) in ./docs then rebuilds -either the staging or production site depending on which branch the changes were made. +## README -To update the Table of Contents (layout of the documentation sidebar), edit the -`config.js` in this directory, while the `README.md` is the landing page for the -website documentation. +The [README.md](./README.md) is also the landing page for the documentation +on the website. -To view the latest documentation on the develop branch, see the staging site: +## Config.js -- https://tendermint-staging.interblock.io/docs/ +The [config.js](./config.js) generates the sidebar and Table of Contents +on the website docs. Note the use of relative links and the omission of +file extensions. Additional features are available to improve the look +of the sidebar. + +## Links + +**NOTE:** Strongly consider the existing links - both within this directory +and to the website docs - when moving or deleting files. + +Relative links should be used nearly everywhere, having discovered and weighed the following: + +### Relative + +Where is the other file, relative to the current one? + +- works both on GitHub and for the VuePress build +- confusing / annoying to have things like: `../../../../myfile.md` +- requires more updates when files are re-shuffled + +### Absolute + +Where is the other file, given the root of the repo? + +- works on GitHub, doesn't work for the VuePress build +- this is much nicer: `/docs/hereitis/myfile.md` +- if you move that file around, the links inside it are preserved (but not to it, of course) + +### Full + +The full GitHub URL to a file or directory. Used occasionally when it makes sense +to send users to the GitHub. + +## Building Locally -and the documentation on master branch is found here: +Not currently possible but coming soon! Doing so requires +assets held in the (private) website repo, installing +[VuePress](https://vuepress.vuejs.org/), and modifying the `config.js`. -- https://tendermint.com/docs/ +## Consistency +Because the build processes are identical (as is the information contained herein), this file should be kept in sync as +much as possible with its [counterpart in the Cosmos SDK repo](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/DOCS_README.md). diff --git a/docs/README.md b/docs/README.md index 8c6c5d105..58b3bcb6b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,7 @@ # Tendermint -Welcome to the Tendermint Core documentation! The introduction below provides -an overview to help you navigate to your area of interest. - -## Introduction +Welcome to the Tendermint Core documentation! Below you'll find an +overview of the documentation. Tendermint Core is Byzantine Fault Tolerant (BFT) middleware that takes a state transition machine - written in any programming language - and securely @@ -11,17 +9,33 @@ replicates it on many machines. In other words, a blockchain. Tendermint requires an application running over the Application Blockchain Interface (ABCI) - and comes packaged with an example application to do so. -Follow the [installation instructions](./introduction/install.md) to get up and running -quickly. For more details on [using tendermint](./tendermint-core/using-tendermint.md) see that -and the following sections. + +## Getting Started + +Here you'll find quick start guides and links to more advanced "get up and running" +documentation. + +## Core + +Details about the core functionality and configuration of Tendermint. + +## Tools + +Benchmarking and monitoring tools. ## Networks -Testnets can be setup manually on one or more machines, or automatically on one -or more machine, using a variety of methods described in the [deploy testnets -section](./networks/deploy-testnets.md). +Setting up testnets manually or automated, local or in the cloud. + +## Apps + +Building appplications with the ABCI. + +## Specification + +Dive deep into the spec. There's one for each Tendermint and the ABCI -## Application Development +## Edit the Documentation -The first step to building application on Tendermint is to [install -ABCI-CLI](./app-dev/getting-started.md) and play with the example applications. +See [this file](./DOCS_README.md) for details of the build process and +considerations when making changes. diff --git a/docs/config.js b/docs/config.js index a006a0756..983f0c678 100644 --- a/docs/config.js +++ b/docs/config.js @@ -27,6 +27,7 @@ module.exports = { "/tendermint-core/configuration", "/tendermint-core/rpc", "/tendermint-core/running-in-production", + "/tendermint-core/fast-sync", "/tendermint-core/how-to-read-logs", "/tendermint-core/block-structure", "/tendermint-core/light-client-protocol", @@ -36,21 +37,23 @@ module.exports = { ] }, { - title: "Tendermint Tools", + title: "Tools", collapsable: false, - children: ["tools/benchmarking", "tools/monitoring"] + children: [ + "tools/benchmarking", + "tools/monitoring" + ] }, { - title: "Tendermint Networks", + title: "Networks", collapsable: false, children: [ "/networks/deploy-testnets", "/networks/terraform-and-ansible", - "/networks/fast-sync" ] }, { - title: "Application Development", + title: "Apps", collapsable: false, children: [ "/app-dev/getting-started", @@ -62,6 +65,37 @@ module.exports = { "/app-dev/abci-spec", "/app-dev/ecosystem" ] + }, + title: "Tendermint Spec", + collapsable: true, + children: [ + "/spec/README", + "/spec/blockchain/blockchain", + "/spec/blockchain/encoding", + "/spec/blockchain/state", + "/spec/consensus/abci", + "/spec/consensus/bft-time", + "/spec/consensus/consensus", + "/spec/consensus/light-client", + "/spec/consensus/wal", + "/spec/p2p/config", + "/spec/p2p/connection", + "/spec/p2p/node", + "/spec/p2p/peer", + "/spec/reactors/block_sync/reactor", + "/spec/reactors/block_sync/impl", + "/spec/reactors/consensus/consensus", + "/spec/reactors/consensus/consensus-reactor", + "/spec/reactors/consensus/proposer-selection", + "/spec/reactors/evidence/reactor", + "/spec/reactors/mempool/concurrency", + "/spec/reactors/mempool/config", + "/spec/reactors/mempool/functionality", + "/spec/reactors/mempool/messages", + "/spec/reactors/mempool/reactor", + "/spec/reactors/pex/pex", + "/spec/reactors/pex/reactor", + ] }, { title: "ABCI Specification", @@ -75,7 +109,10 @@ module.exports = { { title: "Research", collapsable: false, - children: ["/research/determinism", "/research/transactional-semantics"] + children: [ + "/research/determinism", + "/research/transactional-semantics" + ] } ] } diff --git a/docs/networks/fast-sync.md b/docs/tendermint-core/fast-sync.md similarity index 100% rename from docs/networks/fast-sync.md rename to docs/tendermint-core/fast-sync.md