Skip to content

Commit ff97977

Browse files
james-ball-qualcommjames-ball-qualcomm
committed
Add test.adoc and Makefile to ensure tags and norm rules create expected results
Signed-off-by: James Ball <[email protected]>
1 parent 6124035 commit ff97977

File tree

7 files changed

+348
-4
lines changed

7 files changed

+348
-4
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/build/*
2+
*.log

‎Makefile‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Makefile for tests for tools/scripts in docs-resources repository.
2+
# Must be run in top-level directory of docs-resources repository.
3+
#
4+
# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
5+
# International License. To view a copy of this license, visit
6+
# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to
7+
# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
8+
#
9+
# SPDX-License-Identifier: CC-BY-SA-4.0
10+
#
11+
# This Makefile is designed to automate the process of running tests.
12+
# Running with a preinstalled docker container is strongly recommended.
13+
# Install by running:
14+
# docker pull riscvintl/riscv-docs-base-container-image:latest
15+
16+
# Directories all relative to the top-level.
17+
CONVERTERS_DIR := converters
18+
TOOLS_DIR := tools
19+
BUILD_DIR := build
20+
TESTS_DIR := tests
21+
NORM_RULE_TESTS_DIR := $(TESTS_DIR)/norm-rule
22+
NORM_RULE_DEF_DIR := $(NORM_RULE_TESTS_DIR)
23+
NORM_RULE_EXPECTED_DIR := $(NORM_RULE_TESTS_DIR)/expected
24+
25+
# Ruby scripts being tested.
26+
TAGS_BACKEND := tags.rb
27+
CREATE_NORM_RULE_TOOL := create_normative_rules.rb
28+
29+
# Input and output file names
30+
TEST_ADOC_INPUT_FNAME := test.adoc
31+
NORM_TAGS_OUTPUT_FNAME := test-norm-tags.json
32+
NORM_RULE_OUTPUT_FNAME := test-norm-rules.json
33+
34+
# Built output files
35+
BUILT_NORM_TAGS := $(BUILD_DIR)/$(NORM_TAGS_OUTPUT_FNAME)
36+
BUILT_NORM_RULES := $(BUILD_DIR)/$(NORM_RULE_OUTPUT_FNAME)
37+
38+
# Copies of expected output files.
39+
# Use make target "update-expected" to update from build dir contents.
40+
EXPECTED_NORM_TAGS := $(NORM_RULE_EXPECTED_DIR)/$(NORM_TAGS_OUTPUT_FNAME)
41+
EXPECTED_NORM_RULES := $(NORM_RULE_EXPECTED_DIR)/$(NORM_RULE_OUTPUT_FNAME)
42+
43+
DOCKER_BIN ?= docker
44+
SKIP_DOCKER ?= $(shell if command -v ${DOCKER_BIN} >/dev/null 2>&1 ; then echo false; else echo true; fi)
45+
DOCKER_IMG := riscvintl/riscv-docs-base-container-image:latest
46+
ifneq ($(SKIP_DOCKER),true)
47+
DOCKER_IS_PODMAN = \
48+
$(shell ! ${DOCKER_BIN} -v | grep podman >/dev/null ; echo $$?)
49+
ifeq "$(DOCKER_IS_PODMAN)" "1"
50+
# Modify the SELinux label for the host directory to indicate
51+
# that it can be shared with multiple containers. This is apparently
52+
# only required for Podman, though it is also supported by Docker.
53+
DOCKER_VOL_SUFFIX = :z
54+
DOCKER_EXTRA_VOL_SUFFIX = ,z
55+
else
56+
DOCKER_IS_ROOTLESS = \
57+
$(shell ! ${DOCKER_BIN} info -f '{{println .SecurityOptions}}' | grep rootless >/dev/null ; echo $$?)
58+
ifneq "$(DOCKER_IS_ROOTLESS)" "1"
59+
# Rooted Docker needs this flag so that the files it creates are
60+
# owned by the current user instead of root. Rootless docker does not
61+
# require it, and Podman doesn't either since it is always rootless.
62+
DOCKER_USER_ARG := --user $(shell id -u)
63+
endif
64+
endif
65+
66+
DOCKER_CMD = \
67+
${DOCKER_BIN} run --rm \
68+
-v ${PWD}/$@.workdir:/build${DOCKER_VOL_SUFFIX} \
69+
-v ${PWD}/${CONVERTERS_DIR}:/${CONVERTERS_DIR}:ro${DOCKER_EXTRA_VOL_SUFFIX} \
70+
-v ${PWD}/$(TOOLS_DIR):/$(TOOLS_DIR):ro${DOCKER_EXTRA_VOL_SUFFIX} \
71+
-v ${PWD}/$(TESTS_DIR):/$(TESTS_DIR):ro${DOCKER_EXTRA_VOL_SUFFIX} \
72+
-w /build \
73+
$(DOCKER_USER_ARG) \
74+
${DOCKER_IMG} \
75+
/bin/sh -c
76+
DOCKER_QUOTE := "
77+
else
78+
DOCKER_CMD = \
79+
cd $@.workdir &&
80+
endif
81+
82+
WORKDIR_SETUP = \
83+
rm -rf $@.workdir && \
84+
mkdir -p $@.workdir && \
85+
ln -sfn ../../converters ../../tools ../../tests $@.workdir/
86+
87+
WORKDIR_TEARDOWN = \
88+
mv $@.workdir/$@ $@ && \
89+
rm -rf $@.workdir
90+
91+
ASCIIDOCTOR_TAGS := asciidoctor --backend tags --require=./$(CONVERTERS_DIR)/$(TAGS_BACKEND)
92+
93+
OPTIONS := --trace \
94+
-D build \
95+
--failure-level=WARN
96+
97+
.PHONY: all clean tests test-tags test-norm-rules update-expected update-norm-rule-expected
98+
99+
all: tests
100+
tests: test-tags test-norm-rules
101+
test-tags: $(BUILT_NORM_TAGS)
102+
test-norm-rules: $(BUILT_NORM_RULES)
103+
update-expected: update-expected-norm-rule
104+
105+
# All normative rule definition input YAML files tracked under Git (ensure you at least stage new files).
106+
NORM_RULE_DEF_FILES := $(shell git ls-files '$(NORM_RULE_DEF_DIR)/*.yaml')
107+
108+
# Add -t to each normative tag input filename and add prefix of "/" to make into absolute pathname.
109+
NORM_TAG_FILE_ARGS := $(foreach relative_pname,$(BUILT_NORM_TAGS),-t /$(relative_pname))
110+
111+
# Add -d to each normative rule definition filename
112+
NORM_RULE_DEF_ARGS := $(foreach relative_pname,$(NORM_RULE_DEF_FILES),-d $(relative_pname))
113+
114+
update-expected-norm-rule: $(BUILT_NORM_TAGS) $(BUILT_NORM_RULES)
115+
cp -f $(BUILT_NORM_TAGS) $(EXPECTED_NORM_TAGS)
116+
cp -f $(BUILT_NORM_RULES) $(EXPECTED_NORM_RULES)
117+
118+
$(BUILT_NORM_TAGS): $(NORM_RULE_TESTS_DIR)/$(TEST_ADOC_INPUT_FNAME) $(CONVERTERS_DIR)/$(TAGS_BACKEND)
119+
$(WORKDIR_SETUP)
120+
$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_TAGS) $(OPTIONS) -a tags-match-prefix='norm:' -a tags-output-suffix='-norm-tags.json' $< $(DOCKER_QUOTE)
121+
$(WORKDIR_TEARDOWN)
122+
diff $(EXPECTED_NORM_TAGS) $(BUILT_NORM_TAGS)
123+
124+
$(BUILT_NORM_RULES): $(BUILT_NORM_TAGS) $(NORM_RULE_DEF_FILES)
125+
$(WORKDIR_SETUP)
126+
cp -f $(BUILT_NORM_TAGS) $@.workdir
127+
mkdir -p $@.workdir/build
128+
$(DOCKER_CMD) $(DOCKER_QUOTE) ruby $(TOOLS_DIR)/$(CREATE_NORM_RULE_TOOL) $(NORM_TAG_FILE_ARGS) $(NORM_RULE_DEF_ARGS) $@ $(DOCKER_QUOTE)
129+
$(WORKDIR_TEARDOWN)
130+
diff $(EXPECTED_NORM_RULES) $(BUILT_NORM_RULES)
131+
132+
# Update docker image to latest
133+
docker-pull-latest:
134+
${DOCKER_BIN} pull ${DOCKER_IMG}
135+
136+
clean:
137+
@echo "Cleaning up generated files..."
138+
rm -rf $(BUILD_DIR)
139+
@echo "Cleanup completed."

‎normative-rules.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,14 @@ AsciiDoc supports several styles of anchors:
4646
>
4747
> `This isn't part of the anchor since it is the next paragraph.`
4848
49-
* You must use the _paragraph anchor_ for table cells, list items, or description list terms
50-
* For table cells and list items, put the anchor before its associated text as follows:
49+
* You must use the _paragraph anchor_ for table cells, unordered/ordered list items or description list terms
50+
* For table cells and unordered/ordered list items, put the anchor before its associated text as follows:
5151
* Table cell<br>
5252
> `| [[foo]] Here are the table cell contents | next cell`
53-
* List item<br>
54-
> `* [[foo]] Here is the list item`
53+
* Unordered list item<br>
54+
> `* [[foo]] Here is the unordered list item`
55+
* Ordered list item<br>
56+
> `. [[foo]] Here is the ordered list item`
5557
* For description list terms (e.g., `Apples`, `Oranges`), put the anchor immediately after the term on its own line as follows:
5658
> `Apples::`<br>
5759
> `[[apple-colors]]`<br>

‎tests/norm-rule/expected/test-norm-rules.json‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
{
2+
"normative_rules": [
3+
{
4+
"name": "inline",
5+
"def_filename": "tests/norm-rule/test.yaml",
6+
"summary": "A few words",
7+
"tags": [
8+
{
9+
"name": "norm:inline",
10+
"text": "inside inline",
11+
"tag_filename": "/build/test-norm-tags.json"
12+
}
13+
]
14+
},
15+
{
16+
"name": "paragraph",
17+
"def_filename": "tests/norm-rule/test.yaml",
18+
"tags": [
19+
{
20+
"name": "norm:para",
21+
"text": "Paragraph anchor",
22+
"tag_filename": "/build/test-norm-tags.json"
23+
}
24+
]
25+
},
26+
{
27+
"name": "note_with_2_tags",
28+
"def_filename": "tests/norm-rule/test.yaml",
29+
"description": "Here's a description.\nIt's got 2 lines.\n",
30+
"tags": [
31+
{
32+
"name": "norm:note-1",
33+
"text": "Multi-paragraph note 1",
34+
"tag_filename": "/build/test-norm-tags.json"
35+
},
36+
{
37+
"name": "norm:note-3",
38+
"text": "Multi-paragraph note 3",
39+
"tag_filename": "/build/test-norm-tags.json"
40+
}
41+
]
42+
},
43+
{
44+
"name": "desc1",
45+
"def_filename": "tests/norm-rule/test.yaml",
46+
"tags": [
47+
{
48+
"name": "norm:description-item-1",
49+
"text": "Item 1",
50+
"tag_filename": "/build/test-norm-tags.json"
51+
},
52+
{
53+
"name": "norm:description-item-3",
54+
"text": "Item 3",
55+
"tag_filename": "/build/test-norm-tags.json"
56+
}
57+
]
58+
},
59+
{
60+
"name": "desc2",
61+
"def_filename": "tests/norm-rule/test.yaml",
62+
"tags": [
63+
{
64+
"name": "norm:description-item-1",
65+
"text": "Item 1",
66+
"tag_filename": "/build/test-norm-tags.json"
67+
},
68+
{
69+
"name": "norm:description-item-3",
70+
"text": "Item 3",
71+
"tag_filename": "/build/test-norm-tags.json"
72+
}
73+
]
74+
}
75+
]
76+
}

‎tests/norm-rule/expected/test-norm-tags.json‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{
2+
"tags": {
3+
"norm:inline": "inside inline",
4+
"norm:para": "Paragraph anchor",
5+
"norm:description-item-1": "Item 1",
6+
"norm:description-item-3": "Item 3",
7+
"norm:note-1": "Multi-paragraph note 1",
8+
"norm:note-3": "Multi-paragraph note 3"
9+
},
10+
"sections": {
11+
"title": "",
12+
"id": "",
13+
"children": [
14+
{
15+
"title": "Chapter 1",
16+
"id": "_chapter_1",
17+
"children": [
18+
{
19+
"title": "Chapter 1.1",
20+
"id": "_chapter_1_1",
21+
"children": [],
22+
"tags": [
23+
"norm:para"
24+
]
25+
}
26+
],
27+
"tags": [
28+
"norm:inline"
29+
]
30+
},
31+
{
32+
"title": "Chapter 2",
33+
"id": "_chapter_2",
34+
"children": [],
35+
"tags": [
36+
"norm:description-item-1",
37+
"norm:description-item-3",
38+
"norm:note-1",
39+
"norm:note-3"
40+
]
41+
}
42+
],
43+
"tags": []
44+
}
45+
}

‎tests/norm-rule/test.adoc‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// This file contains test AsciiDoc to test the custom AsciiDoctor "tags" backend and the "create_normative_rules" Ruby
2+
// script that consumes the tags to create a list of normative rules.
3+
4+
== Chapter 1
5+
6+
Before inline [#norm:inline]#inside inline# outside inline.
7+
8+
Before bad inline [#norm:bad-inline]#
9+
inside bad inline# outside bad inline.#
10+
11+
=== Chapter 1.1
12+
13+
[[norm:para]]
14+
Paragraph anchor
15+
16+
Next paragraph
17+
18+
Table:
19+
|===
20+
21+
| [[norm:table-cell]] cell contents | next cell
22+
|===
23+
24+
== Chapter 2
25+
26+
Unordered List:
27+
28+
* [[norm:unordered-item-1]] Item 1
29+
* [[norm:unordered-item-2]] Item 2
30+
* Item 3
31+
32+
Ordered List:
33+
34+
. [[norm:ordered-item-1]] Item 1
35+
. [[norm:ordered-item-2]] Item 2
36+
. Item 3
37+
38+
Description List:
39+
40+
Description-1::
41+
[[norm:description-item-1]]
42+
Item 1
43+
44+
Description-2:: Item 2
45+
46+
Description-3::
47+
[[norm:description-item-3]]
48+
Item 3
49+
50+
NOTE: [[norm-note-1]] Single paragraph note
51+
52+
[NOTE]
53+
====
54+
[[norm:note-1]]
55+
Multi-paragraph note 1
56+
57+
Multi-paragraph note 2
58+
59+
[[norm:note-3]]
60+
Multi-paragraph note 3
61+
====

‎tests/norm-rule/test.yaml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# yaml-language-server: $schema=../../schemas/defs-schema.json
2+
3+
$schema: "../../schemas/defs-schema.json#"
4+
5+
# Used to create normative rules for test.adoc file.
6+
7+
normative_rule_definitions:
8+
- name: inline
9+
summary: A few words
10+
tags: ["norm:inline"]
11+
- name: paragraph
12+
tags: ["norm:para"]
13+
- name: note_with_2_tags
14+
description: |
15+
Here's a description.
16+
It's got 2 lines.
17+
tags: ["norm:note-1", "norm:note-3"]
18+
- names: [desc1, desc2]
19+
tags: ["norm:description-item-1", "norm:description-item-3"]

0 commit comments

Comments
 (0)