Merge PR cosmos#5379: New docs V1 (merge master-docs to master)

akash-network · Dec 10, 2019 · b18bd06 · b18bd06
1 parent 7d7821b
commit b18bd06
Show file tree

Hide file tree

Showing 75 changed files with 5,561 additions and 3,631 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -194,6 +194,14 @@ caching through `CommitKVStoreCacheManager`. Any application wishing to utilize
 must set it in their app via a `BaseApp` option. The `BaseApp` docs have been drastically improved
 to detail this new feature and how state transitions occur.
 * (docs/spec) All module specs moved into their respective module dir in x/ (i.e. docs/spec/staking -->> x/staking/spec)
+* (docs/) [\#5379](https://github.com/cosmos/cosmos-sdk/pull/5379) Major documentation refactor, including:
+  * (docs/intro/) Add and improve introduction material for newcomers.
+  * (docs/basics/) Add documentation about basic concepts of the cosmos sdk such as the anatomy of an SDK application, the transaction lifecycle or accounts. 
+  * (docs/core/) Add documentation about core conepts of the cosmos sdk such as `baseapp`, `server`, `store`s, `context` and more. 
+  * (docs/building-modules/) Add reference documentation on concepts relevant for module developers (`keeper`, `handler`, `messages`, `queries`,...).
+  * (docs/interfaces/) Add documentation on building interfaces for the Cosmos SDK.
+  * Redesigned user interface that features new dynamically generated sidebar, build-time code embedding from GitHub, new homepage as well as many other improvements.
+
 
 ### Bug Fixes
 
@@ -206,6 +214,8 @@ to detail this new feature and how state transitions occur.
 * (baseapp) [\#5350](https://github.com/cosmos/cosmos-sdk/issues/5350) Allow a node to restart successfully after a `halt-height` or `halt-time`
   has been triggered.
 
+
+
 ## [v0.37.4] - 2019-11-04
 
 ### Improvements

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -92,10 +92,9 @@ All PRs require two Reviews before merge (except docs changes, or variable name-
 
 If you open a PR on the Cosmos SDK, it is mandatory to update the relevant documentation in /docs.
 
-- If your change relates to the core SDK (baseapp, store, ...), please update the docs/cosmos-hub folder and possibly the docs/spec folder.
-- If your changes relate specifically to the gaia application (not including modules), please modify the docs/cosmos-hub folder.
-- If your changes relate to a module, please update the module's spec in docs/spec. If the module is used by gaia, you might also need to modify docs/cosmos-hub.
-- If your changes relate to the core of the CLI or Light-client (not specifically to module's CLI/Rest), please modify the docs/clients folder.
+- If your change relates to the core SDK (baseapp, store, ...), please update the `docs/basics/`, `docs/core/` and/or `docs/building-modules/` folders.
+- If your changes relate to the core of the CLI or Light-client (not specifically to module's CLI/Rest), please modify the `docs/interfaces/` folder.
+- If your changes relate to a module, please update the module's spec in `x/moduleName/docs/spec/`.
 
 ## Forking
 

diff --git a/README.md b/README.md
@@ -1,3 +1,8 @@
+---
+parent:
+  order: false
+---
+
 # Cosmos SDK
 
 ![banner](docs/cosmos-sdk-image.jpg)
@@ -12,7 +17,7 @@
 [![riot.im](https://img.shields.io/badge/riot.im-JOIN%20CHAT-green.svg)](https://riot.im/app/#/room/#cosmos-sdk:matrix.org)
 
 The Cosmos-SDK is a framework for building blockchain applications in Golang.
-It is being used to build `Gaia`, the first implementation of the Cosmos Hub.
+It is being used to build [`Gaia`](https://github.com/cosmos/gaia), the first implementation of the Cosmos Hub.
 
 **WARNING**: The SDK has mostly stabilized, but we are still making some
 breaking changes.
@@ -23,9 +28,9 @@ breaking changes.
 
 To learn how the SDK works from a high-level perspective, go to the [SDK Intro](./docs/intro/intro.md).
 
-If you want to get started quickly and learn how to build on top of the SDK, please follow the [SDK Application Tutorial](https://github.com/cosmos/sdk-application-tutorial). You can also fork the tutorial's repo to get started building your own Cosmos SDK application.
+If you want to get started quickly and learn how to build on top of the SDK, please follow the [SDK Application Tutorial](https://github.com/cosmos/sdk-application-tutorial). You can also fork the tutorial's repository to get started building your own Cosmos SDK application.
 
-For more, please go to the [Cosmos SDK Docs](./docs/README.md)
+For more, please go to the [Cosmos SDK Docs](./docs/).
 
 ## Cosmos Hub Mainnet
 

diff --git a/docs/.vuepress/components/PageHistory.vue b/docs/.vuepress/components/PageHistory.vue
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -1,95 +1,161 @@
-const glob = require("glob");
-const markdownIt = require("markdown-it");
-const meta = require("markdown-it-meta");
-const fs = require("fs");
-const _ = require("lodash");
-
-const sidebar = (directory, array) => {
-  return array.map(i => {
-    const children = _.sortBy(
-      glob
-        .sync(`./${directory}/${i[1]}/*.md`)
-        .map(path => {
-          const md = new markdownIt();
-          const file = fs.readFileSync(path, "utf8");
-          md.use(meta);
-          md.render(file);
-          const order = md.meta.order;
-          return { path, order };
-        })
-        .filter(f => f.order !== false),
-      ["order", "path"]
-    )
-      .map(f => f.path)
-      .filter(f => !f.match("readme"));
-    return {
-      title: i[0],
-      children
-    };
-  });
-};
-
 module.exports = {
+  theme: "cosmos",
   title: "Cosmos SDK",
-  base: process.env.VUEPRESS_BASE || "/",
+  markdown: {
+    anchor: {
+      permalinkSymbol: ""
+    }
+  },
   locales: {
-    "/": {
-      lang: "en-US"
+    '/': {
+      lang: 'en-US'
+    },
+    'kr': {
+      lang: "kr"
     },
-    "/ru/": {
-      lang: "ru"
+    'cn': {
+      lang: 'cn'
     },
+    'ru': {
+      lang: 'ru'
+    }
   },
+  base: process.env.VUEPRESS_BASE || "/",
   themeConfig: {
     repo: "cosmos/cosmos-sdk",
+    docsRepo: "cosmos/cosmos-sdk",
     docsDir: "docs",
     editLinks: true,
-    docsBranch: "master",
-    locales: {
-      "/": {
-        label: "English",
-        sidebar: sidebar("", [
-          ["Intro", "intro"],
-          ["Basics", "basics"],
-          ["SDK Core", "core"],
-          ["About Modules", "modules"],
-          ["Using the SDK", "sdk"],
-          ["Interfaces", "interfaces"]
-        ])
+    label: "sdk",
+    sidebar: [
+      {
+        title: "Using the SDK",
+        children: [
+          {
+            title: "Modules",
+            directory: true,
+            path: "/modules"
+          },
+        ]
       },
-      "/ru/": {
-        label: "Русский",
-        sidebar: sidebar("ru", [
-          ["Введение", "intro"],
-          ["Основы", "basics"],
-          ["SDK Core", "core"],
-          ["Модули", "modules"],
-          ["Используем SDK", "sdk"],
-          ["Интерфейсы", "interfaces"]
-        ])
+      {
+        title: "Resources",
+        children: [
+          {
+            title: "Tutorials",
+            path: "https://github.com/cosmos/sdk-application-tutorial"
+          },
+          {
+            title: "SDK API Reference",
+            path: "https://godoc.org/github.com/cosmos/cosmos-sdk"
+          },
+          {
+            title: "REST API Spec",
+            path: "https://cosmos.network/rpc/"
+          }
+        ]
+      }
+    ],
+    gutter: {
+      title: "Help & Support",
+      editLink: true,
+      chat: {
+        title: "Riot Chat",
+        text: "Chat with Cosmos developers on Riot Chat.",
+        url: "https://riot.im/app/#/room/#cosmos-sdk:matrix.org",
+        bg: "linear-gradient(225.11deg, #2E3148 0%, #161931 95.68%)"
       },
-      '/kr/': {
-        label: '한국어',
-        sidebar: sidebar('kr', [
-          ['소개', 'intro'],
-          ['기초', 'basics'],
-          ['SDK Core', 'core'],
-          ['모듈들', 'modules'],
-          ['프로그램 사용', 'sdk'],
-          ['인터페이스', 'interfaces'],
-        ]),
+      forum: {
+        title: "Cosmos SDK Forum",
+        text: "Join the SDK Developer Forum to learn more.",
+        url: "https://forum.cosmos.network/",
+        bg: "linear-gradient(225deg, #46509F -1.08%, #2F3564 95.88%)",
+        logo: "cosmos"
       },
-      '/cn/': {
-        label: '中文',
-        sidebar: sidebar('cn', [
-          ['介绍', 'intro'],
-          ['基本', 'basics'],
-          ['SDK Core', 'core'],
-          ['模块', 'modules'],
-          ['使用该程序', 'sdk'],
-          ['接口', 'interfaces'],
-        ]),
+      github: {
+        title: "Found an Issue?",
+        text: "Help us improve this page by suggesting edits on GitHub."
+      }
+    },
+    footer: {
+      logo: "/logo-bw.svg",
+      textLink: {
+        text: "cosmos.network",
+        url: "https://cosmos.network"
       },
+      services: [
+        {
+          service: "medium",
+          url: "https://blog.cosmos.network/"
+        },
+        {
+          service: "twitter",
+          url: "https://twitter.com/cosmos"
+        },
+        {
+          service: "linkedin",
+          url: "https://www.linkedin.com/company/tendermint/"
+        },
+        {
+          service: "reddit",
+          url: "https://reddit.com/r/cosmosnetwork"
+        },
+        {
+          service: "telegram",
+          url: "https://t.me/cosmosproject"
+        },
+        {
+          service: "youtube",
+          url: "https://www.youtube.com/c/CosmosProject"
+        }
+      ],
+      smallprint:
+        "The development of the Cosmos project is led primarily by Tendermint Inc., the for-profit entity which also maintains this website. Funding for this development comes primarily from the Interchain Foundation, a Swiss non-profit.",
+      links: [
+        {
+          title: "Documentation",
+          children: [
+            {
+              title: "Cosmos SDK",
+              url: "https://cosmos.network/docs"
+            },
+            {
+              title: "Cosmos Hub",
+              url: "https://hub.cosmos.network/"
+            }
+          ]
+        },
+        {
+          title: "Community",
+          children: [
+            {
+              title: "Cosmos blog",
+              url: "https://blog.cosmos.network/"
+            },
+            {
+              title: "Forum",
+              url: "https://forum.cosmos.network/"
+            },
+            {
+              title: "Chat",
+              url: "https://riot.im/app/#/room/#cosmos-sdk:matrix.org"
+            }
+          ]
+        },
+        {
+          title: "Contributing",
+          children: [
+            {
+              title: "Contributing to the docs",
+              url: "https://github.com/cosmos/cosmos-sdk/tree/master/docs"
+            },
+            {
+              title: "Source code on GitHub",
+              url: "https://github.com/cosmos/cosmos-sdk/"
+            }
+          ]
+        }
+      ]
     }
   },
   plugins: [

diff --git a/docs/.vuepress/enhanceApp.js b/docs/.vuepress/enhanceApp.js
diff --git a/docs/.vuepress/public/logo-bw.svg b/docs/.vuepress/public/logo-bw.svg