diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md index 01ec07ad..0d1e3f97 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: - -- https://tendermint.com/docs/ - -and built using [VuePress](https://vuepress.vuejs.org/) like below: - -```bash -npm install -g vuepress # global install vuepress tool, only once -npm install - -mkdir -p .vuepress && cp config.js .vuepress/ -vuepress build -``` - -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. - -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. - -To view the latest documentation on the develop branch, see the staging site: +The documentation for Tendermint Core is hosted at: +- https://tendermint.com/docs/ and - https://tendermint-staging.interblock.io/docs/ -and the documentation on master branch is found here: +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. -- https://tendermint.com/docs/ +## How It Works +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. + +## README + +The [README.md](./README.md) is also the landing page for the documentation +on the website. + +## Config.js + +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 + +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`. + +## 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 8c6c5d10..58b3bcb6 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. -## Application Development +## Apps -The first step to building application on Tendermint is to [install -ABCI-CLI](./app-dev/getting-started.md) and play with the example applications. +Building appplications with the ABCI. + +## Specification + +Dive deep into the spec. There's one for each Tendermint and the ABCI + +## Edit the Documentation + +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 a006a075..983f0c67 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