docs: generate module docs from spec (#450)

* docs: generate from spec

* update module spec layout

* minor revisions

* revert proto changes

* revert proto changes

* update module order

* add github markdown

* add github markdown

Co-authored-by: ryanchrypto <12519942+ryanchrypto@users.noreply.github.com>
Co-authored-by: Ru Horlick <ruperthorlick@gmail.com>

docs/.gitignore

@@ -10,3 +10,4 @@ dist
 .basement
 config.local.js
 basement_dist
+modules

docs/.vuepress/config.js

@@ -97,25 +97,60 @@ module.exports = {
           title: 'Modules',
           collapsable: false,
           children: [
+            {
+              title: 'Ecocredit Module',
+              collapsable: false,
+              children: [
+                {
+                  title: 'Overview',
+                  path: '/modules/ecocredit/'
+                },
+                // '/modules/ecocredit/01_concepts',
+                // '/modules/ecocredit/02_state',
+                // '/modules/ecocredit/03_messages',
+                // '/modules/ecocredit/04_events',
+                // '/modules/ecocredit/05_client',
+                {
+                  title: 'Protobuf Documentation',
+                  path: '/modules/ecocredit/protobuf'
+                }
+              ]
+            },
             {
               title: 'Data Module',
               collapsable: false,
               children: [
-                '/modules/data/',
+                {
+                  title: 'Overview',
+                  path: '/modules/data/'
+                },
+                '/modules/data/01_concepts',
+                // '/modules/data/02_state',
+                // '/modules/data/03_messages',
+                // '/modules/data/04_events',
+                // '/modules/data/05_client',
                 {
                   title: 'Protobuf Documentation',
                   path: '/modules/data/protobuf'
                 }
               ]
             },
             {
-              title: 'Ecocredit Module',
+              title: 'Group Module',
               collapsable: false,
               children: [
-                '/modules/ecocredit/',
+                {
+                  title: 'Overview',
+                  path: '/modules/group/'
+                },
+                '/modules/group/01_concepts',
+                '/modules/group/02_state',
+                '/modules/group/03_messages',
+                '/modules/group/04_events',
+                // '/modules/group/05_client',
                 {
                   title: 'Protobuf Documentation',
-                  path: '/modules/ecocredit/protobuf'
+                  path: '/modules/group/protobuf'
                 }
               ]
             },
@@ -139,5 +174,10 @@ module.exports = {
   plugins: [
     '@vuepress/plugin-back-to-top',
     '@vuepress/plugin-medium-zoom',
-  ]
+  ],
+  markdown: {
+    extendMarkdown: md => {
+      md.use(require('./markdown-it-gh'))
+    }
+  }
 }

docs/.vuepress/markdown-it-gh.js

@@ -0,0 +1,48 @@
+var child_process = require("child_process");
+
+function replaceUnsafeChar(ch) {
+  return HTML_REPLACEMENTS[ch];
+}
+
+var HTML_REPLACEMENTS = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+};
+
+function escapeHtml(str) {
+  if (/[&<>"]/.test(str)) {
+    return str.replace(/[&<>"]/g, replaceUnsafeChar);
+  }
+  return str;
+}
+
+module.exports = function asciiDiagram(md, options) {
+  md.renderer.rules.text = function (tokens, idx, options, env) {
+    const a = tokens[idx].content.split(" ");
+    if (a[0] == "+++" && a[1]) {
+      const isGithub = /github.com/.test(a[1]);
+      const url = isGithub
+        ? a[1]
+            .replace("github.com", "raw.githubusercontent.com")
+            .replace("/blob/", "/")
+        : a[1];
+      let data = child_process.spawnSync("curl", [url]).stdout.toString();
+      const hasLines = a[1].match(/#L[0-9]+-L[0-9]+$/);
+      const golang = !!a[1].replace(/#L.*$/, "").match(/\.go$/);
+      if (data && hasLines) {
+        const [lineStart, lineEnd] =
+          hasLines &&
+          hasLines[0].replace(/#/g, "").replace(/L/g, "").split("-");
+        data = data
+          .split("\n")
+          .slice(+lineStart - 1, +lineEnd)
+          .join("\n");
+      }
+      const lang = golang && "go";
+      return `<div class="language-${lang} extra-class"><pre class="language-${lang}"><code>${data}</code></pre></div>`;
+    }
+    return escapeHtml(tokens[idx].content);
+  };
+};

docs/package.json

@@ -9,8 +9,12 @@
   },
   "repository": "https://github.com/regen-network/regen-ledger/docs",
   "scripts": {
+    "predev": "./scripts/pre.sh",
     "dev": "vuepress dev",
-    "build": "vuepress build"
+    "postdev": "./scripts/post.sh",
+    "prebuild": "./scripts/pre.sh",
+    "build": "vuepress build",
+    "postbuild": "./scripts/post.sh"
   },
   "license": "MIT",
   "devDependencies": {

docs/scripts/post.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+rm -rf modules

docs/scripts/pre.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+mkdir -p modules
+
+for D in ../x/*; do
+  if [ -d "${D}" ]; then
+    rm -rf "modules/$(echo $D | awk -F/ '{print $NF}')"
+    mkdir -p "modules/$(echo $D | awk -F/ '{print $NF}')" && cp -r $D/spec/* "$_"
+  fi
+done

scripts/protocgen.sh

@@ -48,7 +48,7 @@ Mgoogle/protobuf/any.proto=github.com/cosmos/cosmos-sdk/codec/types:. \
   buf protoc \
   -I "proto" \
   -I "third_party/proto" \
-  --doc_out=./docs/modules/${module} \
+  --doc_out=./x/${module}/spec \
   --doc_opt=docs/markdown.tmpl,protobuf.md \
   $(find "${dir}" -maxdepth 1 -name '*.proto')
 

docs/modules/data/README.md → x/data/spec/01_concepts.md

@@ -1,7 +1,4 @@
-# Data Module Overview
-
-The data module is intended to be a versatile module for anchoring, signing, 
-and storing data about ecological health, and ecosystem services on Regen Ledger.
+# Concepts
 
 These three functionalities each provide different kinds of information and guarantees
 about the data being referenced.
@@ -13,3 +10,4 @@ about the data being referenced.
 - __Data Storing__: Storing the raw data itself on the blockchain. This is useful when 
   availability guarantees are necessary. This can also be useful in cases where one
   wants smart contracts to have direct access to the data itself.
+

x/data/spec/02_state.md

@@ -0,0 +1 @@
+# State

x/data/spec/03_messages.md

@@ -0,0 +1 @@
+# Msg Service

x/data/spec/04_events.md

@@ -0,0 +1 @@
+# Events

x/data/spec/05_client.md

@@ -0,0 +1,42 @@
+# Client
+
+The `tx` (transaction) and `q` (query) subcommands below give a good illustration
+of how this module can be used in practice:
+
+### Data Transactions
+
+```sh 
+$ regen tx data --help
+# Data transaction subcommands
+# 
+# Usage:
+#   regen tx data [flags]
+#   regen tx data [command]
+# 
+# Available Commands:
+#   anchor      Anchors a piece of data to the blockchain based on its secure
+#                 hash, effectively providing a tamper resistant timestamp.
+#   sign        Sign an arbitrary piece of data on the blockchain.
+#   store       Store a piece of data corresponding to a CID on the blockchain.
+```
+
+### Data Queries
+
+```sh 
+$ regen q data --help
+# Querying commands for the data module.
+# If a CID is passed as first argument, then this command will query
+# timestamp, signers and content (if available) for the given CID. Otherwise,
+# this command will run the given subcommand.
+# 
+# Example (the two following commands are equivalent):
+# $ regen query data bafzbeigai3eoy2ccc7ybwjfz5r3rdxqrinwi4rwytly24tdbh6yk7zslrm
+# $ regen query data by-cid bafzbeigai3eoy2ccc7ybwjfz5r3rdxqrinwi4rwytly24tdbh6yk7zslrm
+# 
+# Usage:
+#   regen query data [cid] [flags]
+#   regen query data [command]
+# 
+# Available Commands:
+#   by-cid      Query for CID timestamp, signers and content (if available)
+```

x/data/spec/README.md

@@ -0,0 +1,20 @@
+# Data Module
+
+::: tip COMING SOON
+The data module is under active development. Check back soon for more information.
+:::
+
+## Abstract
+
+The following documents specify the data module.
+
+The data module is intended to be a versatile module for anchoring, signing, and storing data about ecological health, and ecosystem services on Regen Ledger.
+
+## Contents
+
+1. **[Concepts](01_concepts.md)**
+
+<!-- 2. **[State](02_state.md)**
+3. **[Msg Service](03_messages.md)**
+4. **[Events](04_events.md)**
+5. **[Client](05_client.md)** -->

x/ecocredit/spec/01_concepts.md

@@ -0,0 +1 @@
+# Concepts

x/ecocredit/spec/02_state.md

@@ -0,0 +1 @@
+# State

x/ecocredit/spec/03_messages.md

@@ -0,0 +1 @@
+# Msg Service

x/ecocredit/spec/04_events.md

@@ -0,0 +1 @@
+# Events

docs/modules/ecocredit/README.md → x/ecocredit/spec/05_client.md

@@ -1,15 +1,4 @@
-# Ecocredit Module Overview
-
-::: tip COMING SOON
-
-Expect updates on this page soon...
-
-In the meantime, make sure you're familiar with the basics of the
-[Regen Ledger API & CLI](../../api.md), and then let `regen tx ecocredit --help`
-and the Ecocredit Module [Protobuf Documentation](./protobuf.md)
-be your guide!
-
-:::
+# Client
 
 ### Ecocredit Transactions
 
@@ -29,6 +18,7 @@ $ regen tx ecocredit --help
 #   send          Sends credits from the transaction author (--from) to the recipient
 #   set_precision Allows an issuer to increase the decimal precision of a credit batch
 ```
+
 ### Ecocredit Queries
 
 ```sh

x/ecocredit/spec/README.md

@@ -0,0 +1,19 @@
+# Ecocredit Module
+
+::: tip COMING SOON
+The ecocredit module is under active development. Check back soon for more information.
+:::
+
+## Abstract
+
+The following documents specify the ecocredit module.
+
+The ecocredit module enables the ability to define and manage the issuance of new classes of credits for ecosystem services that represent positive ecological health (i.e. soil health credits, carbon credits, biodiversity credits, etc).
+
+<!-- ## Contents
+
+1. **[Concepts](01_concepts.md)**
+2. **[State](02_state.md)**
+3. **[Msg Service](03_messages.md)**
+4. **[Events](04_events.md)**
+5. **[Client](05_client.md)** -->

x/group/spec/01_concepts.md

@@ -1,7 +1,3 @@
-<!--
-order: 1
--->
-
 # Concepts
 
 ## Group

x/group/spec/02_state.md

@@ -1,7 +1,3 @@
-<!--
-order: 2
--->
-
 # State
 
 The `group` module uses the `orm` package which provides table storage with support for

x/group/spec/03_messages.md

@@ -1,7 +1,3 @@
-<!--
-order: 3
--->
-
 # Msg Service
 
 ## Msg/CreateGroup

x/group/spec/04_events.md

@@ -1,7 +1,3 @@
-<!--
-order: 4
--->
-
 # Events
 
 The group module emits the following events:

x/group/spec/05_client.md

@@ -0,0 +1 @@
+# Client

x/group/spec/README.md

@@ -1,13 +1,8 @@
-<!--
-order: 0
-title: Group
-parent:
-  title: "group"
--->
+# Group Module
 
 ## Abstract
 
-This document specifies the group module.
+The following documents specify the group module.
 
 This module allows the creation and management of on-chain multisig accounts and enables voting for message execution based on configurable decision policies.