Switching from Madoko to AsciiDoc for P4Runtime specification (#510)

* Add reference for RFC2697 in bib Signed-off-by: Dscano <[email protected]> Signed-off-by: Davide Scano <[email protected]> * Switching from Madoko to AsciiDoc for P4Runtime specification Signed-off-by: Davide Scano <[email protected]> * Addressed some comments in the PR Signed-off-by: Davide Scano <[email protected]> * Addressed some comments in the PR, part 2 Signed-off-by: Davide Scano <[email protected]> * Addressed some comments in the PR, part 3 Signed-off-by: Davide Scano <[email protected]> * Addressed some comments in the PR, part 4 Signed-off-by: Davide Scano <[email protected]> * Addressed some comments in the PR, part 5 Signed-off-by: Davide Scano <[email protected]> * Addressed some comments in the PR, part 6 Signed-off-by: Davide Scano <[email protected]> * Addressed some comments in the PR, part 7 Signed-off-by: Davide Scano <[email protected]> * Addressed some comments in the PR, part 8 Signed-off-by: Davide Scano <[email protected]> * Removed trailing whitespace. Add lint script Signed-off-by: Davide Scano <[email protected]> * Changed caption table 7 Signed-off-by: Davide Scano <[email protected]> * Fix tables caption Signed-off-by: Davide Scano <[email protected]> * Proposal to address LibreOffice comment Signed-off-by: Davide Scano <[email protected]> * Implemented proposal (a) to update image and generate via LibreOffice Signed-off-by: Davide Scano <[email protected]> * Remove rogue version from Dockerfile.asciidoc Signed-off-by: Davide Scano <[email protected]> * Fix Dockerfile.asciidoc Signed-off-by: Davide Scano <[email protected]> * README updated, and PNG, SVG images removed from the repo Signed-off-by: Davide Scano <[email protected]> * fix workflows yml Signed-off-by: Dscano <[email protected]> * fix Dockerfile.asciidoc Signed-off-by: Dscano <[email protected]> * Fix the Dockerfile.asciidoc by adding the time. Correct typos in README.md. Signed-off-by: Dscano <[email protected]> * Address issue 528, used correct markup for em-dashes Signed-off-by: Dscano <[email protected]> * Address issue 529, fix incorrect markup for creating links in Asciidoc output Signed-off-by: Dscano <[email protected]> * Proposal issue 525, Some odd syntax highlighting in some code blocks Signed-off-by: Dscano <[email protected]> * Fix trailing whitespace Signed-off-by: Dscano <[email protected]> * Fix trailing whitespace Signed-off-by: Dscano <[email protected]> * Proposal issue 524, fix PDF numbered lists Signed-off-by: Dscano <[email protected]> * Proposal issue 523, fix PDF to avoid breaking bullet items, titles and codes Signed-off-by: Dscano <[email protected]> * Fix issue 522, removed negative indentation Signed-off-by: Dscano <[email protected]> * Fix issue 527, rendering of inline code improved Signed-off-by: Dscano <[email protected]> * Centered images and table captions in HTML Signed-off-by: Dscano <[email protected]> * Add LibreOffice to the Dockerfile and include a new make command. Signed-off-by: Dscano <[email protected]> * Suggest a make command Signed-off-by: Dscano <[email protected]> * Add to Makefile png and svg images generation Signed-off-by: Dscano <[email protected]> * Add images dependencies to Makefile Signed-off-by: Dscano <[email protected]> * Add a Makefile to locally generate the Docker image for AsciiDoc Signed-off-by: Dscano <[email protected]> * Fix scep.yml Signed-off-by: Dscano <[email protected]> * Fix scep.yml second tentative Signed-off-by: Dscano <[email protected]> * Fix scep.yml removed ls Signed-off-by: Dscano <[email protected]> * Add spec check in scep.yml Signed-off-by: Dscano <[email protected]> --------- Signed-off-by: Dscano <[email protected]> Signed-off-by: Davide Scano <[email protected]>
p4lang · Jan 19, 2025 · 7e981d8 · 7e981d8
1 parent da2e344
commit 7e981d8
Show file tree

Hide file tree

Showing 49 changed files with 2,604 additions and 1,948 deletions.
diff --git a/.github/workflows/any-branch-uploads.yml b/.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]' }}

diff --git a/.github/workflows/main-branch-uploads.yml b/.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]

diff --git a/.github/workflows/spec.yml b/.github/workflows/spec.yml
@@ -11,19 +11,21 @@ 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
 
   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
-        ls docs/v1/build
+        make -C docs/tools/
+        docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-asciidoc make build_spec_with_images
+        ls docs/v1/P4Runtime-Spec.pdf
+        ls docs/v1/P4Runtime-Spec.html
diff --git a/.github/workflows/tag-uploads.yml b/.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]

diff --git a/CONTRIBUTING.md b/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`.
diff --git a/docs/tools/Dockerfile.asciidoc b/docs/tools/Dockerfile.asciidoc
@@ -0,0 +1,31 @@
+FROM  ruby:3.3.5
+LABEL maintainer="P4 API Working Group <p4-dev@lists.p4.org>"
+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
diff --git a/docs/tools/Dockerfile.madoko b/docs/tools/Dockerfile.madoko
diff --git a/docs/tools/Makefile b/docs/tools/Makefile
@@ -0,0 +1,3 @@
+all:
+	docker build -t p4rt-asciidoc -f Dockerfile.asciidoc  .
+	docker tag p4rt-asciidoc p4lang/p4rt-asciidoc:latest
diff --git a/docs/tools/README.md b/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

diff --git a/docs/v1/Makefile b/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