[WIP] Add github pages documentation

Generate API documentation for the .proto files

Signed-off-by: James Taylor <[email protected]>

# Conflicts:
#	Makefile
#	buf.gen.yaml

.github/workflows/gh-pages.yml

@@ -0,0 +1,54 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  ci_checks:
+    name: Build checks
+    uses: ./.github/workflows/ci-checks.yml
+
+  build:
+    name: Build documentation
+    needs: ci_checks
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Cache build dependencies
+      uses: actions/cache@v3
+      env:
+        cache-name: makefile-deps
+      with:
+        path: ~/.cache/fabric-protos
+        key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('Makefile') }}
+        restore-keys: |
+          ${{ runner.os }}-${{ env.cache-name }}-${{ hashFiles('Makefile') }}
+          ${{ runner.os }}-${{ env.cache-name }}-
+
+    - name: Run make
+      run: make genprotos
+
+    - name: Get git remote
+      id: get-remote
+      run: echo ::set-output name=REMOTE_URL::$(git remote get-url --push origin)
+
+    - name: Deploy gh-pages
+      run: |
+        git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git config --global user.name "github-actions[bot]"
+        git config --global init.defaultBranch gh-pages
+        git init
+        git add -A
+        git commit -m "Deploy to GitHub Pages"
+        git remote -v
+        git push --force --dry-run $(sed -e "s^://^://$GITHUB_TOKEN@^" <<<$REMOTE_URL) gh-pages:gh-pages
+      working-directory: docs
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        REMOTE_URL: ${{ steps.get-remote.outputs.REMOTE_URL }}

.gitignore

@@ -9,6 +9,7 @@
 .idea
 .vscode
 
+/docs/protos.md
 /google
 /bindings/java/src
 /bindings/node/src

Makefile

@@ -30,6 +30,7 @@ BUF_VERSION := 1.1.1
 BUF_INSTALL_FROM_SOURCE := false
 
 PROTOC_VERSION := 3.19.4
+PROTOC_GEN_DOC_VERSION := 1.5.1
 PROTOC_GEN_GRPC_JAVA_VERSION := 1.45.1
 GRPC_TOOLS_VERSION := 1.11.2
 TS_PROTOC_GEN_VERSION := 0.15.0
@@ -104,6 +105,20 @@ $(PROTOC):
 	@mkdir -p $(dir $(PROTOC))
 	@touch $(PROTOC)
 
+# PROTOC_GEN_DOC points to the marker file for the installed version.
+#
+# If PROTOC_GEN_DOC_VERSION is changed, the binary will be re-downloaded.
+PROTOC_GEN_DOC := $(CACHE_VERSIONS)/protoc-gen-doc/$(PROTOC_GEN_DOC_VERSION)
+$(PROTOC_GEN_DOC):
+	@rm -f $(CACHE_BIN)/protoc-gen-doc
+	@mkdir -p $(CACHE_BIN)
+	$(eval PROTOC_GEN_DOC_TMP := $(shell mktemp -d))
+	cd $(PROTOC_GEN_DOC_TMP); go get github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@v$(PROTOC_GEN_DOC_VERSION)
+	@rm -rf $(PROTOC_GEN_DOC_TMP)
+	@rm -rf $(dir $(PROTOC_GEN_DOC))
+	@mkdir -p $(dir $(PROTOC_GEN_DOC))
+	@touch $(PROTOC_GEN_DOC)
+
 # PROTOC_GEN_GRPC_JAVA points to the marker file for the installed version.
 #
 # If PROTOC_GEN_GRPC_JAVA_VERSION is changed, the binary will be re-downloaded.
@@ -188,7 +203,7 @@ $(GRPC_STATUS_PROTO):
 		-o "$(GRPC_STATUS_PROTO)"
 
 .PHONY: genprotos
-genprotos: $(BUF) $(PROTOC) $(PROTOC_GEN_GRPC_JAVA) $(GRPC_TOOLS) $(TS_PROTOC_GEN) $(GRPC_STATUS_PROTO)
+genprotos: $(BUF) $(PROTOC) $(PROTOC_GEN_DOC) $(PROTOC_GEN_GRPC_JAVA) $(GRPC_TOOLS) $(TS_PROTOC_GEN) $(GRPC_STATUS_PROTO)
 	buf generate --template buf.gen.yaml
 
 .PHONY: javabindings

buf.gen.yaml

@@ -38,6 +38,12 @@ managed:
       peer/snapshot.proto: org.hyperledger.fabric.protos.peer
       peer/transaction.proto: org.hyperledger.fabric.protos.peer
 plugins:
+  - name: doc
+    out: docs
+    opt:
+      - markdown
+      - protos.md
+    strategy: all
   - name: java
     out: bindings/java/src/main/java
   - name: grpc-java

docs/.gitignore

@@ -0,0 +1,7 @@
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+# Ignore folders generated by Bundler
+.bundle/
+vendor/

docs/404.md

@@ -0,0 +1,6 @@
+---
+title: "404 - Page Not Found"
+permalink: /404.html
+---
+
+## The page you wanted does not exist

docs/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'rake'
+gem 'github-pages'
+gem 'jekyll-optional-front-matter'
+gem 'jekyll-titles-from-headings'
+gem 'jekyll-relative-links'