Skip to content

Commit 34c0371

Browse files
thatplguythatplguy
authored
Convert from AsciiDoctor to Material for MkDocs (#80)
1 parent 6f42d52 commit 34c0371

Some content is hidden

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

45 files changed

+5457
-1896
lines changed

‎.github/workflows/deploy-to-web.yml‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,23 +22,20 @@ jobs:
2222
- name: Checkout repository
2323
uses: actions/checkout@v3
2424

25-
- name: Set up Ruby
26-
uses: ruby/setup-ruby@v1
25+
- name: Set up Python
26+
uses: actions/setup-python@v5
2727
with:
28-
ruby-version: '2.7'
28+
python-version: 3.x
2929

30-
- name: Install AsciiDoctor
31-
run: gem install asciidoctor pygments.rb
30+
- name: Install Material for MkDocs
31+
run: pip install mkdocs-material
3232

3333
- name: Clean the build directory
34-
run: rm -rf build/*
34+
run: make clean
3535

3636
- name: Build the tutorial
3737
run: make
3838

39-
- name: Move the tutorial file
40-
run: mv build/tutorial.html build/index.html
41-
4239
- name: Setup Pages
4340
uses: actions/configure-pages@v5
4441

@@ -49,4 +46,4 @@ jobs:
4946

5047
- name: Deploy to GitHub Pages
5148
id: deployment
52-
uses: actions/deploy-pages@v4
49+
uses: actions/deploy-pages@v4

‎.github/workflows/test-tutorial-build.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Test tutorial build
2+
3+
on:
4+
pull_request:
5+
6+
permissions:
7+
contents: read
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v3
16+
17+
- name: Set up Python
18+
uses: actions/setup-python@v5
19+
with:
20+
python-version: 3.x
21+
22+
- name: Install Material for MkDocs
23+
run: pip install mkdocs-material
24+
25+
- name: Clean the build directory
26+
run: make clean
27+
28+
- name: Check that the tutorial builds
29+
run: make

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
build/*
22
/.vscode/
3-
check
3+
check
4+
**.swp
5+
docs/exercises
6+
docs/solutions

‎Makefile‎

Lines changed: 21 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -2,34 +2,33 @@
22

33
MAKEFILE_DIR:=$(dir $(realpath $(lastword $(MAKEFILE_LIST))))
44

5-
default: build exercises build/tutorial.html build/exercises.zip
5+
default: tutorial
66
all: default
77

88
clean:
9-
rm -rf build TAGS
10-
11-
build:
12-
mkdir -p build
13-
mkdir -p build/exercises
14-
mkdir -p build/solutions
9+
rm -rf docs/exercises docs/solutions docs/exercises.zip build TAGS
1510

1611
##############################################################################
1712
# Exercises
1813

1914
SRC_EXAMPLES=$(shell find src/examples -type f)
20-
SOLUTIONS=$(patsubst src/examples/%, build/solutions/%, $(SRC_EXAMPLES))
21-
EXERCISES=$(patsubst src/examples/%, build/exercises/%, $(SRC_EXAMPLES))
15+
SOLUTIONS=$(patsubst src/examples/%, docs/solutions/%, $(SRC_EXAMPLES))
16+
EXERCISES=$(patsubst src/examples/%, docs/exercises/%, $(SRC_EXAMPLES))
2217

2318
CN=cn verify
2419

25-
exercises: $(EXERCISES) $(SOLUTIONS)
20+
exercises: docs-exercises-dirs $(EXERCISES) $(SOLUTIONS)
21+
22+
docs-exercises-dirs:
23+
mkdir -p docs/exercises
24+
mkdir -p docs/solutions
2625

27-
build/exercises/%: src/examples/%
26+
docs/exercises/%: src/examples/%
2827
@echo Rebuild $@
2928
@-mkdir -p $(dir $@)
3029
@sed -E '\|^.*--BEGIN--.*$$|,\|^.*--END--.*$$|d' $< > $@
3130

32-
build/solutions/%: src/examples/%
31+
docs/solutions/%: src/examples/%
3332
@-mkdir -p $(dir $@)
3433
@if [ `which cn` ]; then \
3534
if [[ "$<" = *".c"* ]]; then \
@@ -41,16 +40,15 @@ build/solutions/%: src/examples/%
4140
@echo Rebuild $@
4241
@cat $< | sed '\|^.*--BEGIN--.*$$|d' | sed '\|^.*--END--.*$$|d' > $@
4342

44-
build/exercises.zip: $(EXERCISES)
45-
cd build; zip -r exercises.zip exercises > /dev/null
43+
docs/exercises.zip: $(EXERCISES)
44+
cd docs; zip -r exercises.zip exercises > /dev/null
4645

4746
WORKING=$(wildcard src/examples/list_*.c)
48-
WORKING_AUX=$(patsubst src/examples/%, build/solutions/%, $(WORKING))
49-
temp: $(WORKING_AUX) build
50-
# build/tutorial.html
47+
WORKING_AUX=$(patsubst src/examples/%, docs/solutions/%, $(WORKING))
48+
temp: $(WORKING_AUX) docs-exercises-dirs
5149

5250
##############################################################################
53-
# Check that the examples all run correctly
51+
# Check that the examples all run correctly
5452

5553
CN_PATH?=cn verify
5654

@@ -62,23 +60,16 @@ check-tutorial:
6260
@echo Check tutorial examples
6361
@$(MAKEFILE_DIR)/check.sh "$(CN_PATH)"
6462

65-
check: check-tutorial check-archive
63+
check: check-tutorial check-archive
6664

6765
##############################################################################
6866
# Tutorial document
6967

70-
build/tutorial.adoc build/style.css build/asciidoctor.css: src/tutorial.adoc
71-
@echo Create build/tutorial.adoc
72-
@sed -E 's/include_example\((.+)\)/.link:\1[\1]\n[source,c]\n----\ninclude::\1\[\]\n----/g' $< > $@
73-
@cp src/style.css build
74-
@cp src/asciidoctor.css build
75-
76-
build/images: src/images
77-
cp -r $< $@
68+
tutorial: exercises mkdocs.yml $(shell find docs -type f)
69+
mkdocs build --strict
7870

79-
build/tutorial.html: build/tutorial.adoc $(SRC_EXAMPLES) build/images
80-
asciidoctor --doctype book $< -o $@
81-
@rm build/tutorial.adoc
71+
serve: exercises mkdocs.yml $(shell find docs -type f)
72+
mkdocs serve
8273

8374
##############################################################################
8475
# Misc

‎README.md‎

Lines changed: 44 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,55 @@ View the tutorial here: https://rems-project.github.io/cn-tutorial/
44

55
## Building
66

7+
The CN tutorial is built using [Material for
8+
MkDocs](https://squidfunk.github.io/mkdocs-material/).
9+
10+
Dependencies:
11+
* python 3.x
12+
* pip
13+
14+
```bash
15+
# Install Material for MkDocs
16+
pip install mkdocs-material
17+
18+
# Build the tutorial
19+
make
20+
```
21+
22+
### Hosting locally
23+
24+
You can start a local server that automatically renders changes to the tutorial
25+
files. This is useful while editing the tutorial.
26+
27+
```bash
28+
# Run the docs locally
29+
make serve
30+
```
31+
32+
View at: http://localhost:8000/
33+
734
Install dependencies: [asciidoctor](https://asciidoctor.org/).
835

9-
Run `make` to produce `build/tutorial.html` and its dependencies: especially, `build/exercises/*.c` and `build/solutions/*c`.
36+
## Tutorial examples
37+
38+
The tutorial examples live in [src/examples](./src/examples).
39+
40+
As part of building the tutorial, the examples are lightly preprocessed to
41+
produce solutions and exercises (solutions with the CN specifications removed).
42+
43+
Run `make exercises` to produce the exercises and solutions in the `docs`
44+
directory.
45+
46+
### Testing the tutorial examples
1047

11-
Run `make check-tutorial` to check that all examples in the tutorial have working solutions (except tests with names `*.broken.c`, which are expected to fail). Note that this step will not work until after you have installed CN, which is the first part of the tutorial.
48+
Follow these steps `make check-tutorial` to check that all examples in the tutorial have working solutions (except tests with names `*.broken.c`, which are expected to fail).
1249

13-
Run `make check` to checks both the tutorial and archive examples (see below).
50+
1. Install CN (follow steps in [the tutorial](https://rems-project.github.io/cn-tutorial/
51+
))
52+
2. Run `make check-tutorial`
1453

15-
## CN Example Archive
54+
## CN example archive
1655

1756
The subdirectory `src/example-archive` includes many more examples of CN proofs, both working and broken. See [the README](./src/example-archive/README.md) for a description how these examples are organized.
1857

19-
Run `make check-archive` to check all examples in the example archive.
58+
Install CN and run `make check-archive` to check all examples in the example archive.

‎docs/README.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Welcome to CN
2+
3+
CN is an extension of the C programming language for testing and verifying the
4+
correctness of C code, especially on low-level systems code. Compared to
5+
standard C, CN checks not only that expressions and statements follow the
6+
correct typing discipline for C-types, but also that the C code executes
7+
_safely_ — does not raise C undefined behaviour — and _correctly_ — satisfying
8+
to strong, user-defined specifications.
9+
10+
CN provides utilities for verifying specifications at compile time as well as
11+
automatically generating unit and integration tests to test specifications at
12+
runtime.
13+
14+
This documentation is a work in progress -- your suggestions are greatly
15+
appreciated!
16+
17+
<div class="grid cards" markdown>
18+
19+
- :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
20+
21+
---
22+
23+
Build and install CN and get up and running in minutes
24+
25+
[:octicons-arrow-right-24: Installing CN](getting-started/installation.md)
26+
27+
- :fontawesome-brands-markdown:{ .lg .middle } __Your first spec__
28+
29+
---
30+
31+
Check out the Hello World tutorial to write, test, and verify your first
32+
spec
33+
34+
[:octicons-arrow-right-24: Hello World](getting-started/hello-world.md)
35+
36+
- :material-format-font:{ .lg .middle } __Tutorials__
37+
38+
---
39+
40+
Find tutorials covering common tasks and introducing CN features
41+
42+
[:octicons-arrow-right-24: Tutorials](getting-started/tutorials/README.md)
43+
44+
- :material-scale-balance:{ .lg .middle } __Language reference__
45+
46+
---
47+
48+
Quick reference for CN specification syntax
49+
50+
[:octicons-arrow-right-24: Language reference](reference/README.md)
51+
52+
</div>
53+
54+
## Origins
55+
CN was first described in [CN: Verifying Systems C Code with Separation-Logic Refinement Types](https://dl.acm.org/doi/10.1145/3571194) by Christopher Pulte, Dhruv C. Makwana, Thomas Sewell, Kayvan Memarian, Peter Sewell, and Neel Krishnaswami.
56+
To accurately handle the complex semantics of C, CN builds on the [Cerberus semantics for C](https://github.com/rems-project/cerberus/).
57+
Some of the examples in this tutorial are adapted from Arthur Charguéraud’s excellent
58+
[Separation Logic Foundations](https://softwarefoundations.cis.upenn.edu) textbook, and one of the case studies is based on an
59+
extended exercise due to Bryan Parno.
60+
61+
## Acknowledgment of Support and Disclaimer
62+
This material is based upon work supported by the Air Force Research Laboratory (AFRL) and Defense Advanced Research Projects Agencies (DARPA) under Contract No. FA8750-24-C-B044, a European Research Council (ERC) Advanced Grant “ELVER” under the European Union’s Horizon 2020 research and innovation programme (grant agreement no. 789108), and additional funding from Google. The opinions, findings, and conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the Air Force Research Laboratory (AFRL).
63+
64+
## Building these docs
65+
66+
These docs are built with [Material for
67+
MkDocs](https://squidfunk.github.io/mkdocs-material/). To build and serve them
68+
locally on http://localhost:8000:
69+
70+
```bash
71+
# Install Material for MkDocs
72+
pip install mkdocs-material
73+
74+
# In the cn-tutorial root directory, run
75+
mkdocs serve
76+
```
77+
78+
## Docs layout
79+
80+
mkdocs.yml # The configuration file.
81+
docs/
82+
README.md # The documentation homepage.
83+
... # Other markdown pages, images and other files.

0 commit comments

Comments
 (0)