From 1167e07b988cc1268fc2fc2cbc3059d14f53e51c Mon Sep 17 00:00:00 2001 From: Zach Date: Wed, 19 Sep 2018 13:24:31 -0400 Subject: [PATCH] Merge PR #2341: Link to DOCS_README --- docs/DOCS_README.md | 73 ++++++++++++++++++++++++++++++++++++++------- docs/README.md | 5 ++++ 2 files changed, 68 insertions(+), 10 deletions(-) diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md index da11b2c01e..78451c0ef2 100644 --- a/docs/DOCS_README.md +++ b/docs/DOCS_README.md @@ -1,16 +1,69 @@ -# Documentation Maintenance Overview +# Docs Build Workflow -The documentation found in this directory is hosted at: +The documentation for the Cosmos SDK is hosted at: -- https://cosmos.network/docs/ +- https://cosmos.network/docs/ and +- https://cosmos-staging.interblock.io/docs/ -and built using [VuePress](https://vuepress.vuejs.org/) from the Cosmos website repo: +built from the files in this (`/docs`) directory for +[master](https://github.com/cosmos/cosmos-sdk/tree/master/docs) +and [develop](https://github.com/cosmos/cosmos-sdk/tree/develop/docs), +respectively. -- https://github.com/cosmos/cosmos.network +## How It Works -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. +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. -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. +## 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 Tendermint Core repo](https://github.com/tendermint/tendermint/blob/develop/docs/DOCS_README.md). diff --git a/docs/README.md b/docs/README.md index 9921cd757d..e721ad1a1b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,3 +7,8 @@ Cosmos is a decentralized network of independent parallel blockchains, each powe The first blockchain in the Cosmos Network is the Cosmos Hub, whose native token is the Atom. Cosmos is a permission-less network, meaning that anybody can build a blockchain on it. Cosmos can interoperate with multiple other applications and cryptocurrencies. By creating a new zone, you can plug any blockchain system into the Cosmos hub and pass tokens back and forth between those zones, without the need for an intermediary. + +## Edit the Documentation + +See [this file](./DOCS_README.md) for details of the build process and +considerations when making changes.