Skip to content

Commit 7e981d8

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

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+2604
-1948
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ jobs:
1313
- uses: actions/checkout@v3
1414
- name: Build spec
1515
run: |
16-
docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-madoko:latest make
16+
docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-asciidoc :latest make
1717
ls docs/v1/build
1818
- name: Upload spec to S3 if needed
1919
if: ${{ github.actor != 'dependabot[bot]' }}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ jobs:
1616
fetch-depth: 0
1717
- name: Build spec
1818
run: |
19-
docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-madoko:latest make
19+
docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-asciidoc :latest make
2020
ls docs/v1/build
2121
- name: Upload spec to S3
2222
uses: jakejarvis/s3-sync-action@v0.5.1

‎.github/workflows/spec.yml‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,19 +11,21 @@ on:
1111
- '*-dev'
1212

1313
jobs:
14-
madoko-lint:
14+
asciidoc-lint:
1515
runs-on: [ubuntu-latest]
1616
steps:
1717
- uses: actions/checkout@v3
1818
- name: Run linter
1919
run: |
20-
./tools/madokolint.py docs/v1/P4Runtime-Spec.mdk
20+
./tools/asciidoclint.py docs/v1/P4Runtime-Spec.adoc
2121
2222
build-spec:
2323
runs-on: [ubuntu-latest]
2424
steps:
2525
- uses: actions/checkout@v3
2626
- name: Build spec
2727
run: |
28-
docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-madoko:latest make
29-
ls docs/v1/build
28+
make -C docs/tools/
29+
docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-asciidoc make build_spec_with_images
30+
ls docs/v1/P4Runtime-Spec.pdf
31+
ls docs/v1/P4Runtime-Spec.html

‎.github/workflows/tag-uploads.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
fetch-depth: 0
1919
- name: Build spec
2020
run: |
21-
docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-madoko:latest make
21+
docker run -v `pwd`/docs/v1:/usr/src/p4-spec p4lang/p4rt-asciidoc :latest make
2222
ls docs/v1/build
2323
- name: Upload spec to S3
2424
uses: jakejarvis/s3-sync-action@v0.5.1

‎CONTRIBUTING.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,9 @@ You can fork the repo and submit a pull request in Github.
44

55
All developers must have signed the [P4.org](http://p4.org) CLA.
66

7-
### Madoko style checker
7+
### AsciiDoc style checker
88

9-
The P4Runtime specification is written using
10-
[Madoko](http://madoko.org/reference.html). We provide a lint tool to catch
11-
basic formatting issues and try to keep the spec uniform. The lint tool will be
12-
run as part of CI and patches cannot be merged until it returns success. You can
13-
run the lint tool locally with `./tools/madokolint.py`.
9+
The P4Runtime specification is written using [AsciiDoc](https://docs.asciidoctor.org/).
10+
We provide a lint tool to catch basic formatting issues and try to keep the spec uniform.
11+
The lint tool will be run as part of CI and patches cannot be merged until it returns success. You can
12+
run the lint tool locally with `./tools/asciidoclint.py`.

‎docs/tools/Dockerfile.asciidoc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
FROM ruby:3.3.5
2+
LABEL maintainer="P4 API Working Group <p4-dev@lists.p4.org>"
3+
LABEL description="Dockerfile used for building the asciidoc specification"
4+
5+
RUN apt-get update && \
6+
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
7+
8+
RUN apt-get install -y libreoffice && \
9+
gem install asciidoctor && \
10+
echo 'gem: --no-document' > /etc/gemrc && \
11+
gem install nokogiri && \
12+
gem install rghost && \
13+
gem install asciidoctor-diagram && \
14+
gem install asciidoctor-plantuml && \
15+
gem install asciidoctor-pdf --version 2.3.19 && \
16+
gem install asciidoctor-pdf-cjk && \
17+
gem install asciidoctor-lists --version 1.1.2 && \
18+
gem install coderay pygments.rb thread_safe && \
19+
gem install slim && \
20+
gem install concurrent-ruby && \
21+
gem install haml tilt && \
22+
gem install asciidoctor-mathematical && \
23+
gem install asciidoctor-bibtex &&\
24+
git clone https://github.com/rouge-ruby/rouge &&\
25+
cd rouge && \
26+
git log -n 1 | cat && \
27+
gem build rouge.gemspec && \
28+
gem install rouge
29+
30+
VOLUME ["/usr/src/p4-spec"]
31+
WORKDIR /usr/src/p4-spec

‎docs/tools/Dockerfile.madoko‎

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎docs/tools/Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
all:
2+
docker build -t p4rt-asciidoc -f Dockerfile.asciidoc .
3+
docker tag p4rt-asciidoc p4lang/p4rt-asciidoc:latest

‎docs/tools/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Dockerfile.madoko is used to build a Docker image which we use to render the
1+
Dockerfile.asciidoc is used to build a Docker image which we use to render the
22
P4Runtime specification (HTML & PDF) in CI. The image can also be used locally
33
to build the specification without having to worry about installing all the
44
dependencies yourself.
@@ -9,9 +9,9 @@ simply pull the image from dockerhub and don't have to worry about building the
99
image themselves. If you are a maintainer and you need to upload a new version
1010
of the Docker image to to dockerhub, you will need the following commands:
1111
```bash
12-
docker build -t p4rt-madoko -f Dockerfile.madoko .
13-
docker tag p4rt-madoko p4lang/p4rt-madoko:latest
14-
docker push p4lang/p4rt-madoko:latest
12+
docker build -t p4rt-asciidoc -f Dockerfile.asciidoc .
13+
docker tag p4rt-asciidoc p4lang/p4rt-asciidoc:latest
14+
docker push p4lang/p4rt-asciidoc:latest
1515
```
1616

1717
Note that you need to have write permissions to the p4lang dockerhub repository

‎docs/v1/Makefile‎

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,32 @@
1-
21
SPEC=P4Runtime-Spec
32

4-
all: html pdf build
3+
ROUGE_STYLE=github
4+
ROUGE_CSS=style
5+
6+
all: ${SPEC}.pdf ${SPEC}.html
57

68
build:
7-
mkdir -p build
89

9-
# Note: Brute-force image rendering; could use more precise file-by-file make rules
10-
images: build assets/*.odg
11-
soffice --convert-to svg --outdir build assets/*.odg > /dev/null 2>&1
12-
soffice --convert-to png --outdir build assets/*.odg > /dev/null 2>&1
10+
${SPEC}.pdf: ${SPEC}.adoc images
11+
time asciidoctor-pdf -v \
12+
-a pdf-fontsdir=resources/fonts \
13+
-r asciidoctor-mathematical \
14+
-r asciidoctor-bibtex \
15+
-r asciidoctor-lists \
16+
-a rouge-style=$(ROUGE_STYLE) $<
1317

14-
html: ${SPEC}.mdk p4.json assets/* images
15-
madoko -vv --png --odir=build ${SPEC}.mdk
18+
${SPEC}.html: ${SPEC}.adoc images
19+
time asciidoctor -v \
20+
-r asciidoctor-mathematical \
21+
-r asciidoctor-bibtex \
22+
-r asciidoctor-lists \
23+
-a rouge-css=$(ROUGE_CSS) $<
1624

17-
pdf: ${SPEC}.mdk p4.json assets/* images
18-
madoko --pdf -vv --png --odir=build $<
25+
images:
26+
soffice --convert-to svg --outdir resources/figs resources/figs/*.odg > /dev/null 2>&1
27+
soffice --convert-to png --outdir resources/figs resources/figs/*.odg > /dev/null 2>&1
1928

29+
build_spec_with_images: images all
30+
2031
clean:
21-
${RM} -rf build
32+
/bin/rm -f ${SPEC}.pdf ${SPEC}.html

0 commit comments

Comments
 (0)