#2 - first chunk of adding zq2 documentation. (#8)

* (feat) Start of autogeneration of the Zilliqa 2 API docs.

* (fix) Add a .gitkeep to the cache directory

* (feat) Start of generating index files.

* (feat) More moves towards generating docs.

* (fix) Write files to the correct locations.
(feat) Dockerised build synthesises zq2 documentation

* (feat) A bit more styling.
(feat) Preprocess mkdocs.in.yaml so that we can maintain static pages more easily.
(feat) Log subprocesses run by docgen
(feat) Fix invalid keys in parent.yaml

* (fix) Remove mkdocs.yaml - it's (now) autogenerated

* (fix) Make trunk happy

* (fix) Keep clippy happy

* (fix) Container now builds again.
(feat) Update zq2 version
(fix) Remove spurious z.yaml

* (fix) Remove reference to zilliqa 2 documentation from front page.

* (feat) Makefile: can now use alternate ports.
(fix) Remove old page index

* (fix) Add a .gitkeep to keep trunk fmt happy

* (fix) make trunk happy, using absolutely all the time I have left today :-(

* (fix) Use mainline zq-base

---------

Co-authored-by: Richard Watts <[email protected]>

.gitignore

@@ -49,3 +49,10 @@ secret/*
 
 target/
 **/target/
+
+# Used for checking out versions of zq2
+cache/**
+!cache/.gitkeep
+# Used for rendering API docs.
+zq2/docs/versions/**
+docgen/target

Dockerfile

@@ -1,17 +1,23 @@
-FROM ubuntu:22.04 AS builder
+# Same as zq2 uses, or the z2 build fails :-(
+FROM rust:1.78.0-slim-bullseye as builder
 
 ENV DEBIAN_FRONTEND=noninteractive
 ENV NEEDRESTART_MODE=a
 
 RUN apt-get update && apt-get dist-upgrade -y
-RUN apt-get install -y python3 python3-pip --no-install-recommends
+RUN apt-get install -y python3 python3-pip python3-setuptools --no-install-recommends
+RUN apt-get install -y protobuf-compiler build-essential libssl-dev pkg-config git cmake
+RUN apt autoremove
 
 COPY .  /build
 RUN pip3 install --no-cache-dir -r /build/requirements.txt
 
+
 ENV DOC_SOURCE=docs
 WORKDIR /build/zq1
 RUN  mkdocs build
+WORKDIR /build/docgen
+RUN cargo run /build
 WORKDIR /build/zq2
 ARG VERSION
 ENV VERSION=$VERSION

Makefile

@@ -8,6 +8,8 @@ SHELL := /bin/bash
 ENVIRONMENT ?= dev
 VALID_ENVIRONMENTS := dev stg prd
 
+# Set SERVEOPTS="-a 0.0.0.0:3001" or somesuch to serve at port 3001 on all interfaces.
+
 # Check if the ENVIRONMENT variable is in the list of valid environments
 ifeq ($(filter $(ENVIRONMENT),$(VALID_ENVIRONMENTS)),)
 $(error Invalid value for ENVIRONMENT. Valid values are dev, stg, or prd.)
@@ -19,11 +21,15 @@ HERE=$(shell pwd)
 VERSION=$(shell cat $(HERE)/VERSION)
 export VERSION
 
+.PHONY: autogen dev1 dev2 assemble build run-image push-dev-image image/build-and-push
+zq2/docs/mkdocs.yml autogen:
+	(cd $(HERE)/docgen && cargo run $(HERE))
+
 dev1:
-	(cd zq1 && DOC_SOURCE=$(HERE)/zq1/docs mkdocs serve)
+	(cd zq1 && DOC_SOURCE=$(HERE)/zq1/docs mkdocs serve $(SERVEOPTS))
 
-dev2:
-	(cd zq2 && DOC_SOURCE=$(HERE)/zq2/docs mkdocs serve)
+dev2: zq2/docs/mkdocs.yml
+	(cd zq2 && DOC_SOURCE=$(HERE)/zq2/docs mkdocs serve $(SERVEOPTS))
 
 BINDIR=$(HERE)/obj
 HERE_FILES=Dockerfile requirements.txt