docs: Update README (#2393)

* update DOCS_README
* add spec to docs & other lil fixes (#2402)

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/
-
-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:
 
+- 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).

docs/README.md

@@ -1,9 +1,7 @@
 # Tendermint
 
-Welcome to the Tendermint Core documentation! The introduction below provides
+Welcome to the Tendermint Core documentation! Below you'll find an
-an overview to help you navigate to your area of interest.
+overview of the documentation.
-
-## Introduction
 
 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
+## Getting Started
-and the following sections.
+
+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
+Setting up testnets manually or automated, local or in the cloud.
-or more machine, using a variety of methods described in the [deploy testnets
-section](./networks/deploy-testnets.md).
 
-## Application Development
+## Apps
 
-The first step to building application on Tendermint is to [install
+Building appplications with the ABCI.
-ABCI-CLI](./app-dev/getting-started.md) and play with the example applications.
+
+## 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.

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"
+	]
       }
     ]
   }