docs: Update README (#2393)
* update DOCS_README * add spec to docs & other lil fixes (#2402)
This commit is contained in:
Zach
Alexander Simmerl
parent
fc7f9bcaf6
commit
4fe9906361
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue