[Docs] Introduce Docusaurus documentation (#252)

Introduce the first iteration of dev.poktroll.com using docusarus while also adding a quickstart guide. Done in this PR: - [x] Introduce Docusaurus.io documentation using the `.md` files in this repo - [x] Add a basic quickstart guide - [x] Add a basic contribution guide - [x] Move over existing documents - [x] Add a few admonitions with warning signs & tips - [x] GitHub action to automatically deploy it on merges to main Not done in this PR: - Align the architecture docs with the most up to date architecture - Review all existing (moved over) docs from start to finish Video reference: https://github.com/pokt-network/poktroll/assets/1892194/801a1859-4060-434e-b03e- --------- Co-authored-by: DK <[email protected]> Co-authored-by: h5law <[email protected]>
pokt-network · Dec 20, 2023 · 0bc4a66 · 0bc4a66
1 parent 3cb2373
commit 0bc4a66
Show file tree

Hide file tree

Showing 38 changed files with 17,445 additions and 106 deletions.
diff --git a/.github/workflows/upload-pages-artifact.yml b/.github/workflows/upload-pages-artifact.yml
@@ -0,0 +1,59 @@
+# Based off of https://github.com/LayZeeDK/github-pages-docusaurus
+name: Deploy docusaurus docs to GitHub pages
+
+on:
+  push:
+    branches: ["main"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    permissions:
+      id-token: write
+      pages: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      # 👇 Build steps
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'npm'
+          cache-dependency-path: docusaurus/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd docusaurus
+          npm ci
+
+      - name: Build
+        run: |
+          cd docusaurus
+          npm run build
+
+      # 👆 Build steps
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+        with:
+          enablement: true
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          # 👇 Specify build output path relative to the subdirectory
+          path: docusaurus/build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
+
diff --git a/.gitignore b/.gitignore
@@ -77,3 +77,7 @@ go.work.sum
 
 # TODO_TECHDEBT: It seems that .dot files come and go so we need to figure out the root cause: https://github.com/pokt-network/poktroll/pull/177/files#r1392521547
 # **/*.dot
+
+# Quickstart helpers
+shannon_appgate_config.yaml
+shannon_app_config.yaml
diff --git a/Makefile b/Makefile
@@ -71,6 +71,26 @@ check_godoc:
 	fi; \
 	}
 
+.PHONY: check_npm
+# Internal helper target - check if npm is installed
+check_npm:
+	{ \
+	if ( ! ( command -v npm >/dev/null )); then \
+		echo "Seems like you don't have npm installed. Make sure you install it before continuing"; \
+		exit 1; \
+	fi; \
+	}
+
+.PHONY: check_node
+# Internal helper target - check if node is installed
+check_node:
+	{ \
+	if ( ! ( command -v node >/dev/null )); then \
+		echo "Seems like you don't have node installed. Make sure you install it before continuing"; \
+		exit 1; \
+	fi; \
+	}
+
 
 .PHONY: warn_destructive
 warn_destructive: ## Print WARNING to the user
@@ -117,7 +137,11 @@ localnet_regenesis: ## Regenerate the localnet genesis file
 	mkdir -p $(POKTROLLD_HOME)/config/
 	cp -r ${HOME}/.poktroll/keyring-test $(POKTROLLD_HOME)
 	cp ${HOME}/.poktroll/config/*_key.json $(POKTROLLD_HOME)/config/
-	cp ${HOME}/.poktroll/config/genesis.json $(POKTROLLD_HOME)/config/
+
+# TODO_BLOCKER(@okdas): Figure out how to copy these over w/ a functional state.
+# cp ${HOME}/.poktroll/config/app.toml $(POKTROLLD_HOME)/config/app.toml
+# cp ${HOME}/.poktroll/config/config.toml $(POKTROLLD_HOME)/config/config.toml
+# cp ${HOME}/.poktroll/config/client.toml $(POKTROLLD_HOME)/config/client.toml
 
 ###############
 ### Linting ###
@@ -226,25 +250,18 @@ go_develop_and_test: go_develop go_test ## Generate protos, mocks and run all te
 # TODO_NB                     - An important note to reference later
 # TODO_DISCUSS_IN_THIS_COMMIT - SHOULD NEVER BE COMMITTED TO MASTER. It is a way for the reviewer of a PR to start / reply to a discussion.
 # TODO_IN_THIS_COMMIT         - SHOULD NEVER BE COMMITTED TO MASTER. It is a way to start the review process while non-critical changes are still in progress
-TODO_KEYWORDS = -e "TODO" -e "TODO_COMMUNITY" -e "TODO_DECIDE" -e "TODO_TECHDEBT" -e "TODO_IMPROVE" -e "TODO_OPTIMIZE" -e "TODO_DISCUSS" -e "TODO_INCOMPLETE" -e "TODO_INVESTIGATE" -e "TODO_CLEANUP" -e "TODO_HACK" -e "TODO_REFACTOR" -e "TODO_CONSIDERATION" -e "TODO_IN_THIS_COMMIT" -e "TODO_DISCUSS_IN_THIS_COMMIT" -e "TODO_CONSOLIDATE" -e "TODO_DEPRECATE" -e "TODO_ADDTEST" -e "TODO_RESEARCH" -e "TODO_BUG" -e "TODO_NB"
 
 .PHONY: todo_list
 todo_list: ## List all the TODOs in the project (excludes vendor and prototype directories)
-	grep --exclude-dir={.git,vendor,prototype} -r ${TODO_KEYWORDS}  .
-
-TODO_SEARCH ?= $(shell pwd)
-
-.PHONY: todo_search
-todo_search: ## List all the TODOs in a specific directory specific by `TODO_SEARCH`
-	grep --exclude-dir={.git,vendor,prototype} -r ${TODO_KEYWORDS} ${TODO_SEARCH}
+	grep --exclude-dir={.git,vendor,./docusaurus} -r TODO  .
 
 .PHONY: todo_count
 todo_count: ## Print a count of all the TODOs in the project
-	grep --exclude-dir={.git,vendor,prototype} -r ${TODO_KEYWORDS} . | wc -l
+	grep --exclude-dir={.git,vendor,./docusaurus} -r TODO  . | wc -l
 
 .PHONY: todo_this_commit
 todo_this_commit: ## List all the TODOs needed to be done in this commit
-	grep --exclude-dir={.git,vendor,prototype,.vscode} --exclude=Makefile -r -e "TODO_IN_THIS_COMMIT" -e "TODO_DISCUSS_IN_THIS_COMMIT"
+	grep --exclude-dir={.git,vendor,.vscode} --exclude=Makefile -r -e "TODO_IN_THIS_"
 
 ####################
 ###   Gateways   ###
@@ -527,6 +544,10 @@ go_docs: check_godoc ## Generate documentation for the project
 openapi_gen: ## Generate the OpenAPI spec for the Ignite API
 	ignite generate openapi --yes
 
+.PHONY: docusaurus_start
+docusaurus_start: check_npm check_node ## Start the Docusaurus server
+	(cd docusaurus && npm i && npm run start)
+
 ######################
 ### Ignite Helpers ###
 ######################

diff --git a/README.md b/README.md
diff --git a/README.md b/README.md
@@ -0,0 +1 @@
+docusaurus/docs/README.md
diff --git a/config.yml b/config.yml
@@ -62,6 +62,7 @@ validators:
     bonded: 900000000upokt
     config:
       moniker: "sequencer1"
+
 # We can persist arbitrary genesis values via 1 to 1 mapping to genesis.json
 genesis:
   app_state:

diff --git a/docusaurus/.gitignore b/docusaurus/.gitignore
@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/docusaurus/README.md b/docusaurus/README.md
@@ -0,0 +1,51 @@
+---
+sidebar_position: 4
+title: Website
+---
+
+# Website <!-- omit in toc -->
+
+- [Installation](#installation)
+- [Local Development](#local-development)
+- [Build](#build)
+- [Deployment](#deployment)
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
diff --git a/docusaurus/babel.config.js b/docusaurus/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve("@docusaurus/core/lib/babel/preset")],
+};
diff --git a/docusaurus/docs/README.md b/docusaurus/docs/README.md
@@ -0,0 +1,94 @@
+---
+sidebar_position: 1
+title: Poktroll
+id: home-doc
+slug: /
+---
+
+<div align="center">
+  <a href="https://www.pokt.network">
+    <img src="https://user-images.githubusercontent.com/2219004/151564884-212c0e40-3bfa-412e-a341-edb54b5f1498.jpeg" alt="Pocket Network logo" width="340"/>
+  </a>
+</div>
+
+<div>
+  <a href="https://discord.gg/pokt"><img src="https://img.shields.io/discord/553741558869131266"/></a>
+  <a  href="https://github.com/pokt-network/poktroll/releases"><img src="https://img.shields.io/github/release-pre/pokt-network/pocket.svg"/></a>
+  <a  href="https://github.com/pokt-network/poktroll/pulse"><img src="https://img.shields.io/github/contributors/pokt-network/pocket.svg"/></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg"/></a>
+  <a href="https://github.com/pokt-network/poktroll/pulse"><img src="https://img.shields.io/github/last-commit/pokt-network/pocket.svg"/></a>
+  <a href="https://github.com/pokt-network/poktroll/pulls"><img src="https://img.shields.io/github/issues-pr/pokt-network/pocket.svg"/></a>
+  <a href="https://github.com/pokt-network/poktroll/releases"><img src="https://img.shields.io/badge/platform-linux%20%7C%20macos-pink.svg"/></a>
+  <a href="https://github.com/pokt-network/poktroll/issues"><img src="https://img.shields.io/github/issues/pokt-network/pocket.svg"/></a>
+  <a href="https://github.com/pokt-network/poktroll/issues"><img src="https://img.shields.io/github/issues-closed/pokt-network/pocket.svg"/></a>
+  <a href="https://godoc.org/github.com/pokt-network/pocket"><img src="https://img.shields.io/badge/godoc-reference-blue.svg"/></a>
+  <a href="https://goreportcard.com/report/github.com/pokt-network/pocket"><img src="https://goreportcard.com/badge/github.com/pokt-network/pocket"/></a>
+  <a href="https://golang.org"><img  src="https://img.shields.io/badge/golang-v1.20-green.svg"/></a>
+  <a href="https://github.com/tools/godep" ><img src="https://img.shields.io/badge/godep-dependency-71a3d9.svg"/></a>
+</div>
+
+# poktroll <!-- omit in toc -->
+
+**poktroll** is a rollup built using [Rollkit](https://rollkit.dev/), [Cosmos SDK](https://docs.cosmos.network) and [CometBFT](https://cometbft.com/), created with [Ignite CLI](https://ignite.com/cli) for the Shannon upgrade of the [Pocket Network](https://pokt.network) blockchain.
+
+This R&D effort is the result of a research spike conducted by the Core [Pocket Network](https://pokt.network/) Protocol Team at [GROVE Inc.](https://grove.city/). We have documented our research journey [here](https://www.pokt.network/blog/pokt-network-rolling-into-the-modular-future-of-the-protocol-a-technical-deep-dive) (deep dive) and [here](https://www.pokt.network/blog/a-sovereign-rollup-and-a-modular-future) (summary).
+
+- [Learn about Pocket Network](#learn-about-pocket-network)
+- [Roadmap](#roadmap)
+- [Getting Started](#getting-started)
+  - [Quickstart](#quickstart)
+  - [Godoc](#godoc)
+- [Have questions? Ask An AI](#have-questions-ask-an-ai)
+  - [PNYX (Search Engine)](#pnyx-search-engine)
+  - [GPokT (Chatbot)](#gpokt-chatbot)
+- [License](#license)
+
+## Learn about Pocket Network
+
+User friendly documentation of the Shannon upgrade is still a WIP, but there are
+a handful of (potentially outdated) resources you can reference in the meantime
+to build a better understanding of Pocket Network:
+
+- [Pocket Network official documentation](https://docs.pokt.network)
+- [Pocket Network Morse; aka v0 (current mainnet)](https://github.com/pokt-network/pocket-core)
+- [Pocket Network Protocol (outdated)](https://github.com/pokt-network/pocket-network-protocol)
+- [Pocket Network V1 (deprecated)](https://github.com/pokt-network/pocket)
+
+## Roadmap
+
+You can details related to our roadmap [here](./roadmap/roadmap.md) and the
+roadmap changelog [here](./roadmap/roadmap_changelog.md).
+
+## Getting Started
+
+### Quickstart
+
+The best way to get involved is by following the instructions [here](./quickstart.md).
+
+### Godoc
+
+The Godoc for the source code in this can be found at [pkg.go.dev/github.com/pokt-network/poktroll](https://pkg.go.dev/github.com/pokt-network/poktroll).
+
+## Have questions? Ask An AI
+
+The fastest and easiest way to get answers to your questions is by one of our
+several AI-powered tools.
+
+### PNYX (Search Engine)
+
+You can use [PNYX](https://pnyxai.com/), an AI-powered search engine that has been
+trained and indexed on the Pocket Network documentation, community calls, forums
+and much more!
+
+### GPokT (Chatbot)
+
+You can use our chatbot, [GPokT](https://gpoktn.streamlit.app), to ask questions
+about Pocket Network. Please note that it may require you to provide your own
+LLM API token. If the deployed version of GPokT is down, you can deploy your own
+version by following the instructions [here](https://github.com/pokt-network/gpokt).
+
+---
+
+## License
+
+This project is licensed under the MIT License; see the [LICENSE](https://github.com/pokt-network/poktroll/blob/main/LICENSE) file for details.
diff --git a/docusaurus/docs/architecture/_category_.json b/docusaurus/docs/architecture/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Architecture",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Documentation related to the high-level design, flows and components of the poktroll repo."
+  }
+}