docs: publish static pkg-site generated docs for this repo on GH pages (

#1251)

Preview: https://thehowl.github.io/gno/github.com/gnolang/gno.html

.github/workflows/gh-pages.yml

@@ -21,9 +21,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: "cd misc/devdeps && make install"
-      - run: "cd misc/gendocs && make gen"
-      - run: "find docs/ -type f -ls"
+      - uses: actions/setup-go@v4
+        with:
+          go-version: "1.21.x"
+      - run: "cd misc/gendocs && make install gen"
       - uses: actions/configure-pages@v3
         id: pages
       - uses: actions/upload-pages-artifact@v2

CONTRIBUTING.md

@@ -66,6 +66,11 @@ For Gno, there is no specific tooling that needs to be installed, that’s not a
 You can utilize the `gno` command to facilitate Gnolang support when writing Smart Contracts in Gno, by installing it
 with `make install_gno`.
 
+If you are working on Go source code on this repository, `pkg.go.dev` will not
+render our documentation as it has a license it does not recognise. Instead, use
+the `go doc` command, or use our statically-generated documentation:
+https://gnolang.github.io/gno/github.com/gnolang/gno.html
+
 Additionally, you can also configure your editor to recognize `.gno` files as `.go` files, to get the benefit of syntax
 highlighting.
 

README.md

@@ -103,6 +103,6 @@ We look forward to seeing your first PR!
 
   Pkg.go.dev
 
-  * [![Go Reference](https://pkg.go.dev/badge/github.com/gnolang/gno.svg)](https://pkg.go.dev/github.com/gnolang/gno)
-  * TODO: host custom docs on gh-pages, to bypass license limitation
+  * [![Go Reference](https://pkg.go.dev/badge/hey/google)](https://gnolang.github.io/gno/github.com/gnolang/gno.html) \
+    (pkg.go.dev will not show our repository as it has a license it doesn't recognise)
 </details>

misc/devdeps/Makefile

@@ -1,4 +1,3 @@
 install:
 	go install mvdan.cc/gofumpt
 	go install google.golang.org/protobuf/cmd/protoc-gen-go
-	go install golang.org/x/tools/cmd/godoc

misc/gendocs/Makefile

@@ -1,10 +1,13 @@
 all: clean gen
 
+install:
+	go install golang.org/x/pkgsite/cmd/pkgsite@latest
+
 gen:
 	./gendocs.sh
 
 clean:
 	rm -rf godoc
 
 kill_zombies:
-	kill -9 `lsof -t -i tcp:6060 -s TCP:LISTEN` || true
+	kill -9 `lsof -t -i tcp:8080 -s TCP:LISTEN` || true

misc/gendocs/gendocs.sh

@@ -1,35 +1,51 @@
-#!/bin/sh
-
-GODOC_PORT=${GODOC_PORT:-6060}
-GO_MODULE=${GO_MODULE:-github.com/gnolang/gno}
-GODOC_OUT=${GODOC_OUT:-godoc}
-URL=http://localhost:${GODOC_PORT}/pkg/github.com/gnolang/gno/
-
-echo "[+] Starting godoc server..."
-go run \
-   -modfile ../devdeps/go.mod \
-   golang.org/x/tools/cmd/godoc \
-     -http="localhost:${GODOC_PORT}" &
-PID=$!
-# Waiting for godoc server
-while ! curl --fail --silent "$URL" > /dev/null 2>&1; do
-    sleep 0.1
+#!/bin/bash
+# Heavily modified version of the following script:
+# https://gist.github.com/Kegsay/84ce060f237cb9ab4e0d2d321a91d920
+set -u
+
+DOC_DIR=godoc
+PKG=github.com/gnolang/gno
+
+# Run a pkgsite server which we will scrape. Use env to run it from our repo's root directory.
+env -C ../.. pkgsite &
+DOC_PID=$!
+
+# Wait for the server to init
+while :
+do
+    curl -s "http://localhost:8080" > /dev/null
+    if [ $? -eq 0 ] # exit code is 0 if we connected
+    then
+        break
+    fi
 done
 
-echo "[+] Downloading godoc pages..."
+# Scrape the pkg directory for the API docs. Scrap lib for the CSS/JS. Ignore everything else.
 wget \
-    --recursive \
-    --no-verbose \
-    --convert-links \
-    --page-requisites \
-    --adjust-extension \
-    --execute=robots=off \
-    --include-directories="/lib,/pkg/$GO_MODULE,/src/$GO_MODULE" \
-    --exclude-directories="*" \
-    --directory-prefix="${GODOC_OUT}" \
-    --no-host-directories \
-    "$URL?m=all"
-
-echo "[+] Killing godoc server..."
-kill -9 "$PID"
+	--verbose \
+	--recursive \
+	--mirror \
+	--convert-links \
+	--adjust-extension \
+	--page-requisites \
+	-erobots=off \
+	--accept-regex='8080/((search|license-policy|about|)$|(static|images)/|github.com/gnolang/)' \
+	http://localhost:8080/
+
+# Stop the pkgsite server
+kill -9 $DOC_PID
+
+# Delete the old directory or else mv will put the localhost dir into
+# the DOC_DIR if it already exists.
+rm -rf $DOC_DIR
+mv localhost\:8080 $DOC_DIR
+
+# Perform various replacements to fix broken links/UI.
+# /files/ will point to their github counterparts; we make links to importedby/version go nowhere;
+# any other link will point to pkg.go.dev, and fix the /files/... text when viewing a pkg.
+find godoc -type f -exec sed -ri 's#http://localhost:8080/files/[^"]*/github.com/gnolang/([^/"]+)/([^"]*)#https://github.com/gnolang/\1/blob/master/\2#g
+s#http://localhost:8080/[^"?]*\?tab=(importedby|versions)#\##g
+s#http://localhost:8080([^")]*)#https://pkg.go.dev\1#g
+s#/files/[^" ]*/(github.com/[^" ]*)/#\1#g' {} +
 
+echo "Docs can be found in $DOC_DIR"