1 # Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
2 # file at the top-level directory of this distribution and at
3 # http://rust-lang.org/COPYRIGHT.
5 # Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 # http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 # <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 # option. This file may not be copied, modified, or distributed
9 # except according to those terms.
11 ######################################################################
12 # The various pieces of standalone documentation: guides, tutorial,
15 # The DOCS variable is their names (with no file extension).
17 # PDF_DOCS lists the targets for which PDF documentation should be
20 # RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
21 # rustdoc invocation for xyz.
23 # RUSTDOC_DEPS_xyz are extra dependencies for the rustdoc invocation
26 # L10N_LANGS are the languages for which the docs have been
28 ######################################################################
29 DOCS := index intro tutorial guide guide-ffi guide-macros guide-lifetimes \
30 guide-tasks guide-container guide-pointers guide-testing \
31 guide-runtime complement-bugreport \
32 complement-lang-faq complement-design-faq complement-project-faq rust \
33 rustdoc guide-unsafe guide-strings
35 PDF_DOCS := tutorial rust
37 RUSTDOC_DEPS_rust := doc/full-toc.inc
38 RUSTDOC_FLAGS_rust := --html-in-header=doc/full-toc.inc
42 # Generally no need to edit below here.
44 # The options are passed to the documentation generators.
45 RUSTDOC_HTML_OPTS_NO_CSS = --html-before-content=doc/version_info.html \
46 --html-in-header=doc/favicon.inc \
47 --html-after-content=doc/footer.inc \
48 --markdown-playground-url='http://play.rust-lang.org/'
50 RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
52 PANDOC_BASE_OPTS := --standalone --toc --number-sections
53 PANDOC_TEX_OPTS = $(PANDOC_BASE_OPTS) --include-before-body=doc/version.tex \
54 --from=markdown --include-before-body=doc/footer.tex --to=latex
55 PANDOC_EPUB_OPTS = $(PANDOC_BASE_OPTS) --to=epub
57 # The rustdoc executable...
58 RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
59 # ...with rpath included in case --disable-rpath was provided to
61 RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
66 COMPILER_DOC_TARGETS :=
69 # If NO_REBUILD is set then break the dependencies on rustdoc so we
70 # build the documentation without having to rebuild rustdoc.
72 HTML_DEPS := $(RUSTDOC_EXE)
77 # Check for the various external utilities for the EPUB/PDF docs:
79 ifeq ($(CFG_LUALATEX),)
80 $(info cfg: no lualatex found, deferring to xelatex)
81 ifeq ($(CFG_XELATEX),)
82 $(info cfg: no xelatex found, deferring to pdflatex)
83 ifeq ($(CFG_PDFLATEX),)
84 $(info cfg: no pdflatex found, disabling LaTeX docs)
87 CFG_LATEX := $(CFG_PDFLATEX)
90 CFG_LATEX := $(CFG_XELATEX)
94 CFG_LATEX := $(CFG_LUALATEX)
99 $(info cfg: no pandoc found, omitting PDF and EPUB docs)
104 ######################################################################
106 ######################################################################
108 doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
109 @$(call E, version-stamp: $@)
110 $(Q)echo "$(CFG_VERSION)" >$@
112 HTML_DEPS += doc/version_info.html
113 doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
114 $(wildcard $(D)/*.*) | doc/
115 @$(call E, version-info: $@)
116 $(Q)sed -e "s/VERSION/$(CFG_RELEASE)/; s/SHORT_HASH/$( \
117 CFG_SHORT_VER_HASH)/; \
118 s/STAMP/$(CFG_VER_HASH)/;" $< >$@
120 GENERATED += doc/version.tex doc/version_info.html
122 ######################################################################
123 # Docs, from rustdoc and sometimes pandoc
124 ######################################################################
129 HTML_DEPS += doc/rust.css
130 doc/rust.css: $(D)/rust.css | doc/
132 $(Q)cp -a $< $@ 2> /dev/null
134 HTML_DEPS += doc/favicon.inc
135 doc/favicon.inc: $(D)/favicon.inc | doc/
137 $(Q)cp -a $< $@ 2> /dev/null
139 doc/full-toc.inc: $(D)/full-toc.inc | doc/
141 $(Q)cp -a $< $@ 2> /dev/null
143 HTML_DEPS += doc/footer.inc
144 doc/footer.inc: $(D)/footer.inc | doc/
146 $(Q)cp -a $< $@ 2> /dev/null
148 # The (english) documentation for each doc item.
150 define DEF_SHOULD_BUILD_PDF_DOC
151 SHOULD_BUILD_PDF_DOC_$(1) = 1
153 $(foreach docname,$(PDF_DOCS),$(eval $(call DEF_SHOULD_BUILD_PDF_DOC,$(docname))))
155 doc/footer.tex: $(D)/footer.inc | doc/
156 @$(call E, pandoc: $@)
157 $(CFG_PANDOC) --from=html --to=latex $< --output=$@
160 DOC_TARGETS += doc/not_found.html
161 doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
162 @$(call E, rustdoc: $@)
163 $(Q)$(RUSTDOC) $(RUSTDOC_HTML_OPTS_NO_CSS) \
164 --markdown-css http://doc.rust-lang.org/rust.css $<
169 DOC_TARGETS += doc/$(1).html
170 doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
171 @$$(call E, rustdoc: $$@)
172 $$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
174 ifneq ($(ONLY_HTML_DOCS),1)
176 # EPUB (pandoc directly)
177 DOC_TARGETS += doc/$(1).epub
178 doc/$(1).epub: $$(D)/$(1).md | doc/
179 @$$(call E, pandoc: $$@)
180 $$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) $$< --output=$$@
182 # PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
183 DOC_TARGETS += doc/$(1).tex
184 doc/$(1).tex: $$(D)/$(1).md doc/footer.tex doc/version.tex | doc/
185 @$$(call E, pandoc: $$@)
186 $$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) $$< --output=$$@
188 ifneq ($(NO_PDF_DOCS),1)
189 ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
190 DOC_TARGETS += doc/$(1).pdf
192 doc/$(1).pdf: doc/$(1).tex
193 @$$(call E, latex compiler: $$@)
195 -interaction=batchmode \
196 -output-directory=doc \
199 # The version of xelatex on the snap bots seemingly ingores -output-directory
200 # So we'll output to . and move to the doc directory manually.
201 # This will leave some intermediate files in the build directory.
202 doc/$(1).pdf: doc/$(1).tex
203 @$$(call E, latex compiler: $$@)
205 -interaction=batchmode \
206 -output-directory=. \
208 $$(Q)mv ./$(1).pdf $$@
210 endif # SHOULD_BUILD_PDF_DOCS_$(1)
213 endif # ONLY_HTML_DOCS
217 $(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
220 # Localized documentation
222 # FIXME: I (huonw) haven't actually been able to test properly, since
223 # e.g. (by default) I'm doing an out-of-tree build (#12763), but even
224 # adjusting for that, the files are too old(?) and are rejected by
227 # As such, I've attempted to get it working as much as possible (and
228 # switching from pandoc to rustdoc), but preserving the old behaviour
229 # (e.g. only running on the tutorial)
231 l10n-mds: $(D)/po4a.conf \
232 $(foreach lang,$(L10N_LANG),$(D)/po/$(lang)/*.md.po)
233 $(warning WARNING: localized documentation is experimental)
234 po4a --copyright-holder="The Rust Project Developers" \
235 --package-name="Rust" \
236 --package-version="$(CFG_RELEASE)" \
241 DOC_L10N_TARGETS += doc/l10n/$(1)/$(2).html
242 doc/l10n/$(1)/$(2).html: l10n-mds $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(2))
243 @$$(call E, rustdoc: $$@)
244 $$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) doc/l10n/$(1)/$(2).md
247 $(foreach lang,$(L10N_LANGS),$(eval $(call DEF_L10N_DOC,$(lang),tutorial)))
250 ######################################################################
251 # LLnextgen (grammar analysis from refman)
252 ######################################################################
254 ifeq ($(CFG_LLNEXTGEN),)
255 $(info cfg: no llnextgen found, omitting grammar-verification)
257 .PHONY: verify-grammar
259 doc/rust.g: $(D)/rust.md $(S)src/etc/extract_grammar.py
260 @$(call E, extract_grammar: $@)
261 $(Q)$(CFG_PYTHON) $(S)src/etc/extract_grammar.py $< >$@
263 verify-grammar: doc/rust.g
264 @$(call E, LLnextgen: $<)
265 $(Q)$(CFG_LLNEXTGEN) --generate-lexer-wrapper=no $< >$@
266 $(Q)rm -f doc/rust.c doc/rust.h
270 ######################################################################
271 # Rustdoc (libstd/extra)
272 ######################################################################
275 # The library documenting macro
277 # $(1) - The crate name (std/extra)
279 # Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
282 # If NO_REBUILD is set then break the dependencies on rustdoc so we
283 # build crate documentation without having to rebuild rustdoc.
284 ifeq ($(NO_REBUILD),)
289 $$(foreach dep,$$(RUST_DEPS_$(1)), \
290 $$(TLIB2_T_$(CFG_BUILD)_H_$(CFG_BUILD))/stamp.$$(dep) \
293 LIB_DOC_DEP_$(1) = $$(CRATEFILE_$(1)) $$(RSINPUTS_$(1))
299 $(2) += doc/$(1)/index.html
300 doc/$(1)/index.html: CFG_COMPILER_HOST_TRIPLE = $(CFG_TARGET)
301 doc/$(1)/index.html: $$(LIB_DOC_DEP_$(1)) doc/$(1)/
302 @$$(call E, rustdoc: $$@)
303 $$(Q)$$(RUSTDOC) --cfg dox --cfg stage2 $$<
306 $(foreach crate,$(DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),DOC_TARGETS)))
307 $(foreach crate,$(COMPILER_DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),COMPILER_DOC_TARGETS)))
309 ifdef CFG_DISABLE_DOCS
310 $(info cfg: disabling doc build (CFG_DISABLE_DOCS))
312 COMPILER_DOC_TARGETS :=
316 compiler-docs: $(COMPILER_DOC_TARGETS)
318 docs-l10n: $(DOC_L10N_TARGETS)