Switching from Madoko to AsciiDoc for P4Runtime specification

.github/workflows/any-branch-uploads.yml

@@ -13,7 +13,7 @@ jobs:
     - uses: actions/checkout@v3
     - name: Build spec
       run: |
-        docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-madoko:latest make
+        docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-asciidoc :latest make
         ls docs/v1/build
     - name: Upload spec to S3 if needed
       if: ${{ github.actor != 'dependabot[bot]' }}

.github/workflows/main-branch-uploads.yml

@@ -16,7 +16,7 @@ jobs:
         fetch-depth: 0
     - name: Build spec
       run: |
-        docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-madoko:latest make
+        docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-asciidoc :latest make
         ls docs/v1/build
     - name: Upload spec to S3
       uses: jakejarvis/[email protected]

.github/workflows/spec.yml

@@ -11,19 +11,27 @@ on:
       - '*-dev'
 
 jobs:
-  madoko-lint:
+  asciidoc-lint:
     runs-on: [ubuntu-latest]
     steps:
     - uses: actions/checkout@v3
     - name: Run linter
       run: |
-        ./tools/madokolint.py docs/v1/P4Runtime-Spec.mdk
+        ./tools/asciidoclint.py docs/v1/P4Runtime-Spec.adoc
+
+  docker:
+    runs-on: [ubuntu-latest]
+    steps:
+    - uses: actions/checkout@v3
+    - name: Run docker
+      run: |
+        make -C docs/tools/
 
   build-spec:
     runs-on: [ubuntu-latest]
     steps:
     - uses: actions/checkout@v3
     - name: Build spec
       run: |
-        docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-madoko:latest make
+        docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-asciidoc :latest make build_spec_with_images
         ls docs/v1/build

.github/workflows/tag-uploads.yml

@@ -18,7 +18,7 @@ jobs:
         fetch-depth: 0
     - name: Build spec
       run: |
-        docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-madoko:latest make
+        docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-asciidoc :latest make
         ls docs/v1/build
     - name: Upload spec to S3
       uses: jakejarvis/[email protected]

CONTRIBUTING.md

@@ -4,10 +4,9 @@ You can fork the repo and submit a pull request in Github.
 
 All developers must have signed the [P4.org](http://p4.org) CLA.
 
-### Madoko style checker
+### AsciiDoc style checker
 
-The P4Runtime specification is written using
-[Madoko](http://madoko.org/reference.html). We provide a lint tool to catch
-basic formatting issues and try to keep the spec uniform. The lint tool will be
-run as part of CI and patches cannot be merged until it returns success. You can
-run the lint tool locally with `./tools/madokolint.py`.
+The P4Runtime specification is written using [AsciiDoc](https://docs.asciidoctor.org/).
+We provide a lint tool to catch basic formatting issues and try to keep the spec uniform. 
+The lint tool will be run as part of CI and patches cannot be merged until it returns success. You can
+run the lint tool locally with `./tools/asciidoclint.py`.

docs/tools/Dockerfile.asciidoc

@@ -0,0 +1,31 @@
+FROM  ruby:3.3.5
+LABEL maintainer="P4 API Working Group <[email protected]>"
+LABEL description="Dockerfile used for building the asciidoc specification"
+
+RUN  apt-get update && \
+     apt-get install -y cmake flex bison libglib2.0-dev libcairo2-dev libpango1.0-dev libxml2-dev libwebp-dev libzstd-dev libgdk-pixbuf-2.0-dev time
+
+RUN   apt-get install -y libreoffice && \
+      gem install asciidoctor && \
+      echo 'gem: --no-document' > /etc/gemrc && \
+      gem install nokogiri && \
+      gem install rghost && \
+      gem install asciidoctor-diagram && \
+      gem install asciidoctor-plantuml && \
+      gem install asciidoctor-pdf --version 2.3.19 && \
+      gem install asciidoctor-pdf-cjk && \
+      gem install asciidoctor-lists --version 1.1.2 && \
+      gem install coderay pygments.rb thread_safe && \
+      gem install slim && \
+      gem install concurrent-ruby && \
+      gem install haml tilt && \
+      gem install asciidoctor-mathematical && \
+      gem install asciidoctor-bibtex &&\
+      git clone https://github.com/rouge-ruby/rouge &&\
+      cd rouge && \
+      git log -n 1 | cat && \
+      gem build rouge.gemspec && \ 
+      gem install rouge 
+
+VOLUME ["/usr/src/p4-spec"]
+WORKDIR /usr/src/p4-spec

docs/tools/Makefile

@@ -0,0 +1,3 @@
+all:
+	docker build -t p4rt-asciidoc -f Dockerfile.asciidoc  .
+	docker tag p4rt-asciidoc p4lang/p4rt-asciidoc:latest

docs/tools/README.md

@@ -1,4 +1,4 @@
-Dockerfile.madoko is used to build a Docker image which we use to render the
+Dockerfile.asciidoc  is used to build a Docker image which we use to render the
 P4Runtime specification (HTML & PDF) in CI. The image can also be used locally
 to build the specification without having to worry about installing all the
 dependencies yourself.
@@ -9,9 +9,9 @@ simply pull the image from dockerhub and don't have to worry about building the
 image themselves. If you are a maintainer and you need to upload a new version
 of the Docker image to to dockerhub, you will need the following commands:
 ```bash
-docker build -t p4rt-madoko -f Dockerfile.madoko .
-docker tag p4rt-madoko p4lang/p4rt-madoko:latest
-docker push p4lang/p4rt-madoko:latest
+docker build -t p4rt-asciidoc -f Dockerfile.asciidoc  .
+docker tag p4rt-asciidoc p4lang/p4rt-asciidoc:latest
+docker push p4lang/p4rt-asciidoc:latest
 ```
 
 Note that you need to have write permissions to the p4lang dockerhub repository

docs/v1/Makefile

@@ -1,21 +1,32 @@
-
 SPEC=P4Runtime-Spec
 
-all: html pdf build
+ROUGE_STYLE=github
+ROUGE_CSS=style
+
+all: ${SPEC}.pdf ${SPEC}.html
 
 build:
-	mkdir -p build
 
-# Note: Brute-force image rendering; could use more precise file-by-file make rules
-images: build assets/*.odg
-	soffice --convert-to svg --outdir build assets/*.odg > /dev/null 2>&1
-	soffice --convert-to png --outdir build assets/*.odg > /dev/null 2>&1
+${SPEC}.pdf: ${SPEC}.adoc images
+	time asciidoctor-pdf -v \
+	-a pdf-fontsdir=resources/fonts \
+	-r asciidoctor-mathematical \
+	-r asciidoctor-bibtex \
+	-r asciidoctor-lists \
+	-a rouge-style=$(ROUGE_STYLE) $<
 
-html: ${SPEC}.mdk p4.json assets/* images
-	madoko -vv --png --odir=build ${SPEC}.mdk
+${SPEC}.html: ${SPEC}.adoc images
+	time asciidoctor -v \
+	-r asciidoctor-mathematical \
+	-r asciidoctor-bibtex \
+	-r asciidoctor-lists \
+	-a rouge-css=$(ROUGE_CSS) $<
 
-pdf: ${SPEC}.mdk p4.json assets/* images
-	madoko --pdf -vv --png --odir=build $<
+images:
+	soffice --convert-to svg --outdir resources/figs resources/figs/*.odg > /dev/null 2>&1
+	soffice --convert-to png --outdir resources/figs resources/figs/*.odg > /dev/null 2>&1
 
+build_spec_with_images: images all
+
 clean:
-	${RM} -rf build
+	/bin/rm -f ${SPEC}.pdf ${SPEC}.html