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
|
# RJL: This will make literate documents via pycco in docs/literate
# Run this makefile via
#
# make -f MakeLiterate...
#
# You should note that pycco gets confused sometimes and its output
# can be a little garbled, but it can help to understand other
# people's code more easily.
MAKEFLAGS += --warn-undefined-variables
MAKEFLAGS += --no-builtin-rules
RST2HTML := rst2html5.py --initial-header-level=2 --footnote-references=superscript --smart-quotes=yes -g -d -t
PDOC := pdoc --html --overwrite --all-submodules --html-dir
# Updated by RJL 13th May with more sensible behaviour
# For some reason it won't generate SQL files
# We build or rebuild the documentation with pycco - shorthand for the command here in PYCCO_ALL variable
# This one builds the index.html file
PYCCO_ALL := pycco --generate_index --paths -s --directory
# This one does NOT build the index file - otherwise, if you pass a single file
# it will be the ONLY one in the index. Do'h!
PYCCO_ONE := pycco --paths -s --directory
# We want to look at all the .py files in the Code directory (where we start)
# in case any have changed. The makefile is in /Code so we just use './'
# the shell for 'this directory that we are in' - so the following means
# 'all the files ending in "py" in this directory'
PYSOURCES=$(wildcard *.py)
PYSUBSOURCES=$(wildcard lib/*.py)
PYTESTSOURCES=$(wildcard lib/tests/*.py)
PYWIDGESTSOURCES=$(wildcard lib/widgets/*.py)
PYEXTRASOURCES=$(wildcard lib/extra/*.py)
ALL_SOURCES=$(PYSOURCES) $(PYSUBSOURCES) $(PYTESTSOURCES) $(PYWIDGESTSOURCES) $(PYEXTRASOURCES)
# This is how we extract an html file-name for each changed python file-name
# It basically reads: for each .py file in the source directory (PYSOURCES),
# there should be a matching .html file in Code_Documentation.
# The % means the stem, for example world.py has a stem of 'world' so we
# make world.html from world.py
DOCUMENTS_NEEDED_BASE=$(PYSOURCES:%.py=docs/literate/%.html)
# For subdirectories, we'll get the subdirectory as a prefix
# for example, lib/widgets
DOCUMENTS_NEEDED_SUB=$(PYSUBSOURCES:%.py=docs/literate/%.html)
# What to do if we just type 'make' without any parameters - we generate the docs
.DEFAULT_GOAL := all
# No such file as all so mark it as a phony
.PHONY: all
.PHONY: base
.PHONY: svrsub
.PHONY: sqlfiles
base: $(DOCUMENTS_NEEDED_BASE)
svrsub: $(DOCUMENTS_NEEDED_SUB)
all: sqlfiles base svrsub
# The html file in docs/literate (and its cousins) depends upon the py file of the same name
# If the html file is missing or older than the python one, run the pycco command
# for the file (in $<)
docs/literate/lib/%.html: %.py
$(PYCCO_ONE) ./docs/literate $<
docs/literate/%.html: %.py
$(PYCCO_ONE) ./docs/literate $<
# Call 'make index' to make the full documentation
.PHONY: index
index:
make clean
$(PYCCO_ALL) ./docs/literate $(ALL_SOURCES)
.PHONY: clean
clean:
rm -rf docs/literate
|