Browse Source

docs: Update README (#2393)

* update DOCS_README
* add spec to docs & other lil fixes (#2402)
pull/2426/head
Zach 6 years ago
committed by Alexander Simmerl
parent
commit
4fe9906361
4 changed files with 127 additions and 38 deletions
  1. +57
    -19
      docs/DOCS_README.md
  2. +27
    -13
      docs/README.md
  3. +43
    -6
      docs/config.js
  4. +0
    -0
      docs/tendermint-core/fast-sync.md

+ 57
- 19
docs/DOCS_README.md View File

@ -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).

+ 27
- 13
docs/README.md View File

@ -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.

+ 43
- 6
docs/config.js View File

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


docs/networks/fast-sync.md → docs/tendermint-core/fast-sync.md View File


Loading…
Cancel
Save