docs/Makefile at master · andreww591/docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# The following rules generate a yaml file that contains file modification metadata
# provided by git.  The format is:
#
# date: Tue Mar 13 19:11:51 2018 +1100
# timestamps:
#   - page: BuildSystemAnatomy/index.md
#     date: Tue Mar 13 19:11:51 2018 +1100
#   - page: CAmkESDifferences.md
#     date: Tue Mar 13 19:11:51 2018 +1100
# ...
# If this prebuild _data generation step gets more complicated then it should
# probably be moved to a python script.

FILE_NAME=_data/generated.yml

UPDATE_DATE:= $(shell git log -1 --format='%cd %h')
FILES:= $(shell find -iname "*.md" | grep -ve "./README.md" | sed 's/.\///')

SEL4_GIT_URL=https://github.com/seL4/seL4.git
TUTORIALS_GIT_URL=https://github.com/sel4proj/sel4-tutorials.git
CAPDL_GIT_URL=https://github.com/sel4/capdl.git

DOCKER_IMG:=docs_builder

$(dir $(FILE_NAME)):
	mkdir -p $@

_generate_git_site_timestamp: $(dir $(FILE_NAME))
	echo "date: $(UPDATE_DATE)" > $(FILE_NAME)

_generate_git_per_page_timestamps: _generate_git_site_timestamp
	echo timestamps: >> $(FILE_NAME) && \
	for i in $(FILES); do \
		echo "  - page: $$i" >> $(FILE_NAME) &&\
		echo "    date: `git log -1 --format='%cd %h' -- $$i`" >> $(FILE_NAME); \
	done

generate_data_files: _generate_git_per_page_timestamps

_repos/sel4-tutorials:
	git clone $(TUTORIALS_GIT_URL) _repos/sel4-tutorials
	git clone $(CAPDL_GIT_URL) _repos/capdl
	mkdir -p _repos/tutes

_repos/tutes/%.md: _repos/sel4-tutorials/tutorials/%
	PYTHONPATH=_repos/capdl/python-capdl-tool _repos/sel4-tutorials/template.py --docsite --out-dir _repos/tutes --tut-file $</$(@F)

TUTORIALS:= $(filter-out index.md,$(notdir $(wildcard Tutorials/*.md)))
tutorials: ${TUTORIALS:%=_repos/tutes/%}

_repos/sel4:
	git clone $(SEL4_GIT_URL) _repos/sel4

_generate_api_pages: _repos/sel4
	$(MAKE) markdown -C _repos/sel4/manual

generate_api: _generate_api_pages

# Rules for local serving of the site using jekyll.
# Supports docker or running using local environment.
# The _production versions run with JEKYLL_ENV=production which will show additional content.
# The _production versions require `generate_data_files` to have been run separately.
JEKYLL_ENV:=development

docker_serve: docker_build
	docker run --network=host -v $(PWD):/docs -w /docs -it $(DOCKER_IMG) bash -c 'bundle install && $(MAKE) generate_api && JEKYLL_ENV=$(JEKYLL_ENV) bundle exec jekyll serve'

docker_serve_production:
	$(MAKE) docker_serve JEKYLL_ENV=production

docker_build:
	docker build -t $(DOCKER_IMG) tools/

serve: generate_api
	JEKYLL_ENV=$(JEKYLL_ENV) bundle exec jekyll serve

serve_production:
	$(MAKE) serve JEKYLL_ENV=production

# Check conformance for Web Content Accessibility Guidelines (WCAG) 2.0, AA
# This relies on Automated Accessibility Testing Tool (AATT) (https://github.com/paypal/AATT)
# to be running and listening on http://localhose:3000
# The resulting conformance_results.xml file can be viewed with `make check_conformance_errors` or using a junit xml viewer
check_conformance: generate_api
	bundle exec jekyll build
	find _site -iname "*.html"| sed "s/_site.//" | python tools/testWCAG.py > conformance_results.xml

check_conformance_errors: conformance_results.xml
	grep -B1 'type="failure"' conformance_results.xml || true

LIQUID_CUSTOM_TAGS := continue

LIQUID_LINTER_CMDLINE := liquid-linter $(LIQUID_CUSTOM_TAGS:%=--custom-tag %)

# Liquid syntax linting check.
# If it is complaining about unknown custom tags -> add them to the list above.
# Requires `liquid-linter` to be installed.
# git ls-files won't list any files that are untracked
check_liquid_syntax:
	git ls-files "*.html" | xargs $(LIQUID_LINTER_CMDLINE)
	git ls-files "*.md" | xargs $(LIQUID_LINTER_CMDLINE)

# Output html checking using tidy.
# Any warnings or errors will be printed to stdout
# Requires `tidy` to be installed.
check_html_output: generate_api
	bundle exec jekyll build
	find _site/ -iname "*.html"| xargs -l tidy -q --drop-empty-elements n -e