Makefile 8.29 KB
Newer Older
Glenn Walbran's avatar
Glenn Walbran committed
1
2
3
4
5
6
7
8
9
# Makefile for Sphinx documentation


# You can set these variables from the command line.
SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
PAPER         =
BUILDDIR      = build
MAHARA        =
10
TRANSLATIONS  = en de fr ja nl
Glenn Walbran's avatar
Glenn Walbran committed
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

# TRANSLATIONS_UNSUPPORTED = ja
# TODO: Building Japanese language PDFs with LaTeX is non-trivial and poorly documented.
# TODO: Complicating it with Sphinx has made it pretty much impossible. Good luck!

# Internal variables.
PAPEROPT_a4     = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

.PHONY: help clean update html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest

help:
	@echo "Please use \`make <target>' where <target> is one of"
	@echo "  html       to make standalone HTML files"
	@echo "  dirhtml    to make HTML files named index.html in directories"
	@echo "  singlehtml to make a single large HTML file"
	@echo "  pickle     to make pickle files"
	@echo "  json       to make JSON files"
	@echo "  htmlhelp   to make HTML files and a HTML help project"
	@echo "  qthelp     to make HTML files and a qthelp project"
	@echo "  devhelp    to make HTML files and a Devhelp project"
	@echo "  epub       to make an epub"
	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
	@echo "  text       to make text files"
	@echo "  man        to make manual pages"
	@echo "  changes    to make an overview of all changed/added/deprecated items"
	@echo "  linkcheck  to check all external links for integrity"
	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"

clean:
	-rm -rf $(BUILDDIR)/*
	-rm -rf source/locales/*

# This is used by the build cronjob to checkout the correct manual version.
update:
	git checkout .
	git checkout $(MAHARA)_STABLE
	git pull

52
53
54
generatepot:
	$(SPHINXBUILD) -b gettext source potfiles

Glenn Walbran's avatar
Glenn Walbran committed
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
fetchtranslations:
	/bin/bash generate-mo-files.sh $(MAHARA)
	#Delete translated images submodule, then init/update it from remote
	-rm -rf source/images-translated
	#Update/init/remote to effective clone from HEAD
	-git submodule update --init --remote source/images-translated

preview:
	$(SPHINXBUILD) -a -D language=en -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html/en/$(MAHARA)
	@echo
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/en/$(MAHARA)."

html: fetchtranslations
	@$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(TRANSLATION)/$(MAHARA); \
		echo "---------------"; \
	)
72
	@cp manual-build/source/index.html $(BUILDDIR)/html/
Glenn Walbran's avatar
Glenn Walbran committed
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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
	@echo
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/<language>/$(MAHARA)."

dirhtml:
	$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml/$(TRANSLATION)/$(MAHARA) \
	;)
	@echo
	@echo "Build finished. The dirhtml pages are in $(BUILDDIR)/dirhtml/<language>/$(MAHARA)."

singlehtml:
	$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml/$(TRANSLATION)/$(MAHARA) \
	;)
	@echo
	@echo "Build finished. The singlehtml pages are in $(BUILDDIR)/singlehtml/<language>/$(MAHARA)."

pickle:
	$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle/$(TRANSLATION)/$(MAHARA) \
	;)
	@echo
	@echo "Build finished. The pickle pages are in $(BUILDDIR)/pickle/<language>/$(MAHARA)."

json:
	$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json/$(TRANSLATION)/$(MAHARA) \
	;)
	@echo
	@echo "Build finished. The json pages are in $(BUILDDIR)/json/<language>/$(MAHARA)."

htmlhelp:
	$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(TRANSLATION)/$(MAHARA) \
	;)
	@echo
	@echo "Build finished; now you can run HTML Help Workshop with the" \
	      ".hhp project file in $(BUILDDIR)/htmlhelp/<language>/$(MAHARA)."

qthelp:
	$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp/$(TRANSLATION)/$(MAHARA) \
	;)
	@echo
	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
	      ".qhcp project file in $(BUILDDIR)/qthelp/<language>/$(MAHARA), like this:"
	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Mahara.qhcp"
	@echo "To view the help file:"
	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/<language>/$(MAHARA)/Mahara.qhc"

devhelp:
	$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp/$(TRANSLATION)/$(MAHARA) \
	;)
	@echo
	@echo "Build finished."
	@echo "To view the help file:"
	@echo "# mkdir -p $$HOME/.local/share/devhelp/Mahara"
	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Mahara"
	@echo "# devhelp"

epub: fetchtranslations
135
	#TODO delete the cp below when doc publishing no longer needs it. Because epub should depend on html
Glenn Walbran's avatar
Glenn Walbran committed
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
	@$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(TRANSLATION)/$(MAHARA); \
		cp $(BUILDDIR)/epub/$(TRANSLATION)/$(MAHARA)/Mahara.epub $(BUILDDIR)/html/$(TRANSLATION)/$(MAHARA)/Mahara.epub; \
		echo "---------------"; \
	)
	@echo
	@echo "Build finished. The epub files have been moved to $(BUILDDIR)/html/<language>/$(MAHARA)/Mahara.epub."

latex: fetchtranslations
	@$(foreach TRANSLATION,$(TRANSLATIONS), \
        echo "Translation [$(TRANSLATION)]..."; \
		sphinxlang=$(TRANSLATION) $(SPHINXBUILD) -a -D language=$(TRANSLATION) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA); \
		echo "---------------"; \
	)
	@echo
	@echo "Build finished. The latex pages are in $(BUILDDIR)/latex/<language>/$(MAHARA)."
	@echo "Run \`make' in that directory to run these through (pdf)latex" \
	      "(use \`make latexpdf' here to do that automatically)."


156
# build the pdf twice to ensure the table of contents is generated
Glenn Walbran's avatar
Glenn Walbran committed
157
158
159
160
latexpdf: latex
	@$(foreach TRANSLATION,$(TRANSLATIONS), \
        echo "Translation [$(TRANSLATION)]..."; \
	    sed -i s/,dvipdfmx// $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/Mahara.tex; \
161
	    $(MAKE) PDFLATEX="xelatex -halt-on-error -file-line-error" -C $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) all-pdf|grep -P -A2 ":[0-9]+:\ .*|Error:"; \
Glenn Walbran's avatar
Glenn Walbran committed
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
	    $(MAKE) PDFLATEX="xelatex -halt-on-error -file-line-error" -C $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) all-pdf|grep -P -A2 ":[0-9]+:\ .*|Error:"; \
		echo "---------------"; \
	)
	@echo
	@echo "Build finished. The PDF files are in $(BUILDDIR)/latex/<language>/$(MAHARA)."
	@echo "   NOTE: Japanese language PDF, if built, probably failed. This is expected for now."

text:
	$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text/$(TRANSLATION)/$(MAHARA) \
	;)
	@echo
	@echo "Build finished. The text pages are in $(BUILDDIR)/text/<language>/$(MAHARA)."

man:
	$(foreach TRANSLATION,$(TRANSLATIONS), \
		$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man/$(TRANSLATION)/$(MAHARA) \
	;)
	@echo
	@echo "Build finished. The manual pages are in $(BUILDDIR)/man/<language>/$(MAHARA)."

changes:
	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
	@echo
	@echo "The overview file is in $(BUILDDIR)/changes."

linkcheck:
	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
	@echo
	@echo "Link check complete; look for any errors in the above output " \
	      "or in $(BUILDDIR)/linkcheck/output.txt."

doctest:
	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
	@echo "Testing of doctests in the sources finished, look at the " \
	      "results in $(BUILDDIR)/doctest/output.txt."
198

199
bundle: html epub
200
201
202
203
204
205
	@$(foreach TRANSLATION,$(TRANSLATIONS), \
		cp $(BUILDDIR)/epub/$(TRANSLATION)/$(MAHARA)/Mahara.epub $(BUILDDIR)/html/$(TRANSLATION)/$(MAHARA)/Mahara.epub; \
	)
	@tar -czf $(BUILDDIR)/mahara-manual$(MAHARA).tar.gz -C $(BUILDDIR)/html $(TRANSLATIONS)
	@echo
	@echo "Created bundle: $(BUILDDIR)/mahara-manual$(MAHARA).tar.gz"