Merge pull request p4lang#1332 from jafingerhut/replace-madoko-spec-w…

…ith-asciidoc-try4

Replace Madoko language spec and PSA spec with Asciidoc

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

@@ -0,0 +1,29 @@
+name: Any branch uploads
+
+on:
+  push:
+    branches:
+      - '**'
+
+jobs:
+  any-branch-uploads:
+    if: ${{ github.repository == 'p4lang/p4-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/p4-spec-asciidoc:latest make
+        ls docs/v1/build
+    - name: Upload spec to S3 if needed
+      if: ${{ github.actor != 'dependabot[bot]' }}
+      uses: jakejarvis/[email protected]
+      with:
+        args: --acl public-read --follow-symlinks --delete
+      env:
+        AWS_S3_BUCKET: 'p4-spec'
+        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        AWS_REGION: 'us-west-2'
+        SOURCE_DIR: 'docs/v1/build'
+        DEST_DIR: ci/${{ github.ref_name }} # only runs for push events

.github/workflows/asciidoc-build.yml

@@ -0,0 +1,116 @@
+name: Build and push specification files
+
+on:
+  push:
+    branches:
+      - '**'
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        # Fetch all history for all branches
+        fetch-depth: 0
+
+    - name: Install asciidoc
+      run: sudo ./p4-16/spec/install-asciidoctor-linux.sh
+
+    - name: Build p4-16/spec
+      run: |
+        source /usr/local/rvm/scripts/rvm
+        make -C p4-16/spec
+
+    - name: Build p4-16/psa
+      run: |
+        source /usr/local/rvm/scripts/rvm
+        make -C p4-16/psa
+
+    - name: Build api/charter
+      run: |
+        source /usr/local/rvm/scripts/rvm
+        make -C api/charter
+
+    - name: Upload spec artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: spec
+        path: |
+          p4-16/spec/P4-16-spec.html
+          p4-16/spec/P4-16-spec.pdf
+          p4-16/spec/resources/figs
+
+    - name: Upload PSA spec artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: psa-spec
+        path: |
+          p4-16/psa/PSA.html
+          p4-16/psa/PSA.pdf
+          p4-16/psa/charter/P4_Arch_Charter.html
+          p4-16/psa/figs
+
+    - name: Upload API charter artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: api-charter
+        path: |
+          api/charter/P4_API_WG_charter.pdf
+
+  deploy:
+    needs: build
+    if: github.repository == 'p4lang/p4-spec' && github.ref_name == 'main'
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        # Fetch all history for all branches
+        fetch-depth: 0
+
+    - name: Rebase gh-pages branch
+      run: |
+        git checkout gh-pages
+        git rebase --quiet main
+
+    - name: Download spec artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: spec
+        path: spec
+
+    - name: Download PSA spec artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: psa-spec
+        path: psa-spec
+
+    - name: Download API charter artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: api-charter
+        path: api-charter
+
+    - name: Configure git
+      run: |
+        git config user.name "GitHub Actions"
+        git config user.email "[email protected]"
+
+    - name: Copy files
+      run: |
+        pwd
+        ls -l *
+        cp spec/P4-16-spec.html docs/P4-16-working-spec.html
+        cp spec/P4-16-spec.pdf docs/P4-16-working-spec.pdf
+        cp psa-spec/PSA.html docs/PSA.html
+        cp psa-spec/PSA.pdf docs/PSA.pdf
+        cp psa-spec/charter/P4_Arch_Charter.html docs/
+        cp api-charter/P4_API_WG_charter.pdf docs/
+
+    - name: Commit changes
+      run: |
+        git add docs/P4-16-working-spec.{html,pdf} docs/PSA.{html,pdf} docs/P4_API_WG_charter.pdf docs/P4_Arch_Charter.html
+        git commit -am "docs for ${{ steps.vars.outputs.sha_short }}"
+
+    - name: Push commit to gh-pages branch
+      run: git push -f origin gh-pages
+

.gitignore

@@ -0,0 +1,3 @@
+*.sw*
+!.github
+rouge

api/charter/.gitignore

@@ -1 +1,2 @@
 build/
+*.pdf

api/charter/Makefile

@@ -1,8 +1,11 @@
-
 SPEC=P4_API_WG_charter
+ROUGE_STYLE=molokai
+ROUGE_CSS=style
 
-build/${SPEC}.pdf: ${SPEC}.mdk
-	madoko -vv --png --odir=build $<
+${SPEC}.pdf: ${SPEC}.adoc
+	asciidoctor-pdf -v \
+		-a pdf-fontsdir=resources/fonts \
+		-a rouge-style=$(ROUGE_STYLE) $<
 
 clean:
 	${RM} -rf build

api/charter/P4_API_WG_charter.mdk → api/charter/P4_API_WG_charter.adoc

@@ -1,23 +1,27 @@
-Title         : P4 API WG Charter
+= P4 API Working Group Charter
+:doctype: book
+:revdate: {docdate}
+:font-size: 10
+:pdf-themesdir: resources/theme/
+:pdf-theme: p4-theme.yml
+:source-highlighter: rouge
 
-[TITLE]
-
-# Working Group Name
+== Working Group Name
 
 P4 API Working Group
 
-# Chairs
+== Chairs
 
 - Antonin Bas <[email protected]>
 - Lorenzo Vicisano <[email protected]>
 
-# Mailing Lists
+== Mailing Lists
 
 - To subscribe, visit
-  [http://lists.p4.org/mailman/listinfo/p4-api_lists.p4.org](http://lists.p4.org/mailman/listinfo/p4-api_lists.p4.org)
+  http://lists.p4.org/mailman/listinfo/p4-api_lists.p4.org
 - To post a message to all list members, end an email to <[email protected]>
 
-# Description of the Working Group
+== Description of the Working Group
 
 The P4 language is designed to specify the dataplane of networking devices by
 combining a number of core abstractions, such as parsers, tables and externs.
@@ -32,28 +36,28 @@ runtime APIs for P4 device management. To complement these P4 runtime APIs, this
 working group will also specify the relationship between P4 runtime objects and
 entities that appear in the switch configuration, such as ports and
 platform-level functions. A practical way to achieve this would be, for example,
-to define an [OpenConfig](http://http://openconfig.net/) schema specific to a
+to define an https://openconfig.net[OpenConfig] schema specific to a
 switch that exposes a P4 runtime API.
 
 A P4 runtime API should support two main pieces of functionality:
 
-- managing the behavior of the dataplane objects described in a P4 program and
+* managing the behavior of the dataplane objects described in a P4 program and
 retrieving information from these objects when needed. For example, in the case
 of match-action tables, adding entries to the table, removing them and
 retrieving the table content.
-- (re)configuring the forwarding pipeline in a P4-programmable device, by
+* (re)configuring the forwarding pipeline in a P4-programmable device, by
 pushing a new P4 program to the device.
 
 We anticipate that the above functionality will require defining at least the
 following features:
 
-- runtime management of P4 tables
-- runtime management of Portable Standard Architecture (PSA) externs
-- ability to extend the API to support vendor-specific externs
-- session management, which includes updating the P4 program running on the
+* runtime management of P4 tables
+* runtime management of Portable Standard Architecture (PSA) externs
+* ability to extend the API to support vendor-specific externs
+* session management, which includes updating the P4 program running on the
 device and packet IO between the control-plane and the device.
 
-# Deliverables
+== Deliverables
 
 The first item of work for the Working Group will be to define a
 vendor-independent, protocol-independent way for a control-plane to configure,
@@ -67,5 +71,5 @@ Group is called P4Runtime and will target a remote controller.
 3. A specification of the configuration bindings necessary for P4 runtime
 control expressed as an OpenConfig schema in YANG format.
 4. A working opensource implementation of 1. and 3., including a client and
-server libraries and bindings for the [p4lang software
-switch](https://github.com/p4lang/behavioral-model).
+server libraries and bindings for the
+https://github.com/p4lang/behavioral-model[p4lang software switch].

api/charter/resources/fonts

@@ -0,0 +1 @@
+../../../p4-16/spec/resources/fonts

api/charter/resources/theme/logo.png

@@ -0,0 +1 @@
+../../../../p4-16/spec/resources/theme/logo.png

api/charter/resources/theme/p4-theme.yml

@@ -0,0 +1 @@
+../../../../p4-16/spec/resources/theme/p4-theme.yml

p4-16/psa/.gitignore

@@ -0,0 +1,2 @@
+PSA.html
+PSA.pdf

p4-16/psa/Makefile

@@ -1,14 +1,18 @@
 .PHONY: charter
 
 SPEC=PSA
+ROUGE_STYLE=github
+ROUGE_CSS=style
 
-all: build/${SPEC}.pdf charter
+all: ${SPEC}.pdf ${SPEC}.html charter
 
-build/${SPEC}.pdf: ${SPEC}.mdk
-	madoko --pdf -vv --png --odir=build $<
+${SPEC}.pdf: ${SPEC}.adoc
+	asciidoctor-pdf -v \
+		-a pdf-fontsdir=resources/fonts \
+		-a rouge-style=$(ROUGE_STYLE) $<
 
-build/${SPEC}.pdf: p4.json
-build/${SPEC}.pdf: psa.p4
+${SPEC}.html: ${SPEC}.adoc
+	asciidoctor -v -a rouge-css=$(ROUGE_CSS) $<
 
 charter:
 	$(MAKE) -C charter