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.
14 # The DOCS variable is their names (with no file extension).
16 # PDF_DOCS lists the targets for which PDF documentation should be
19 # RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
20 # rustdoc invocation for xyz.
22 # RUSTDOC_DEPS_xyz are extra dependencies for the rustdoc invocation
25 # L10N_LANGS are the languages for which the docs have been
27 ######################################################################
28 DOCS := index intro tutorial \
29 complement-lang-faq complement-design-faq complement-project-faq \
30 rustdoc reference grammar
32 # Legacy guides, preserved for a while to reduce the number of 404s
33 DOCS += guide-crates guide-error-handling guide-ffi guide-macros guide \
34 guide-ownership guide-plugins guide-pointers guide-strings guide-tasks \
40 RUSTDOC_DEPS_reference := doc/full-toc.inc
41 RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
45 # Generally no need to edit below here.
47 # The options are passed to the documentation generators.
48 RUSTDOC_HTML_OPTS_NO_CSS = --html-before-content=doc/version_info.html \
49 --html-in-header=doc/favicon.inc \
50 --html-after-content=doc/footer.inc \
51 --markdown-playground-url='https://play.rust-lang.org/'
53 RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
55 PANDOC_BASE_OPTS := --standalone --toc --number-sections
56 PANDOC_TEX_OPTS = $(PANDOC_BASE_OPTS) --from=markdown --to=latex \
57 --include-before-body=doc/version.tex \
58 --include-before-body=doc/footer.tex \
59 --include-in-header=doc/uptack.tex
60 PANDOC_EPUB_OPTS = $(PANDOC_BASE_OPTS) --to=epub
62 # The rustdoc executable...
63 RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
64 # ...with rpath included in case --disable-rpath was provided to
66 RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
68 # The rustbook executable...
69 RUSTBOOK_EXE = $(HBIN2_H_$(CFG_BUILD))/rustbook$(X_$(CFG_BUILD))
70 # ...with rpath included in case --disable-rpath was provided to
72 RUSTBOOK = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTBOOK_EXE)
74 # The error-index-generator executable...
75 ERR_IDX_GEN_EXE = $(HBIN2_H_$(CFG_BUILD))/error-index-generator$(X_$(CFG_BUILD))
76 ERR_IDX_GEN = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(ERR_IDX_GEN_EXE)
80 DOC_TARGETS := trpl nomicon style error-index
81 COMPILER_DOC_TARGETS :=
84 # If NO_REBUILD is set then break the dependencies on rustdoc so we
85 # build the documentation without having to rebuild rustdoc.
87 HTML_DEPS := $(RUSTDOC_EXE)
94 ifneq ($(CFG_XELATEX),)
95 CFG_LATEX := $(CFG_XELATEX)
98 $(info cfg: no xelatex found, disabling LaTeX docs)
102 ifeq ($(CFG_PANDOC),)
103 $(info cfg: no pandoc found, omitting PDF and EPUB docs)
108 ######################################################################
110 ######################################################################
112 doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
113 @$(call E, version-stamp: $@)
114 $(Q)echo "$(CFG_VERSION)" >$@
116 HTML_DEPS += doc/version_info.html
117 doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
118 $(wildcard $(D)/*.*) | doc/
119 @$(call E, version-info: $@)
120 $(Q)sed -e "s/VERSION/$(CFG_RELEASE)/; \
121 s/SHORT_HASH/$(CFG_SHORT_VER_HASH)/; \
122 s/STAMP/$(CFG_VER_HASH)/;" $< >$@
124 GENERATED += doc/version.tex doc/version_info.html
126 ######################################################################
127 # Docs, from rustdoc and sometimes pandoc
128 ######################################################################
133 HTML_DEPS += doc/rust.css
134 doc/rust.css: $(D)/rust.css | doc/
136 $(Q)cp -PRp $< $@ 2> /dev/null
138 HTML_DEPS += doc/favicon.inc
139 doc/favicon.inc: $(D)/favicon.inc | doc/
141 $(Q)cp -PRp $< $@ 2> /dev/null
143 doc/full-toc.inc: $(D)/full-toc.inc | doc/
145 $(Q)cp -PRp $< $@ 2> /dev/null
147 HTML_DEPS += doc/footer.inc
148 doc/footer.inc: $(D)/footer.inc | doc/
150 $(Q)cp -PRp $< $@ 2> /dev/null
152 # The (english) documentation for each doc item.
154 define DEF_SHOULD_BUILD_PDF_DOC
155 SHOULD_BUILD_PDF_DOC_$(1) = 1
157 $(foreach docname,$(PDF_DOCS),$(eval $(call DEF_SHOULD_BUILD_PDF_DOC,$(docname))))
159 doc/footer.tex: $(D)/footer.inc | doc/
160 @$(call E, pandoc: $@)
161 $(CFG_PANDOC) --from=html --to=latex $< --output=$@
163 doc/uptack.tex: $(D)/uptack.tex | doc/
167 DOC_TARGETS += doc/not_found.html
168 doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
169 @$(call E, rustdoc: $@)
170 $(Q)$(RUSTDOC) $(RUSTDOC_HTML_OPTS_NO_CSS) \
172 --markdown-css https://doc.rust-lang.org/rust.css $<
177 DOC_TARGETS += doc/$(1).html
178 doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
179 @$$(call E, rustdoc: $$@)
180 $$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
182 ifneq ($(ONLY_HTML_DOCS),1)
184 # EPUB (pandoc directly)
185 DOC_TARGETS += doc/$(1).epub
186 doc/$(1).epub: $$(D)/$(1).md | doc/
187 @$$(call E, pandoc: $$@)
188 $$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) $$< --output=$$@
190 # PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
191 DOC_TARGETS += doc/$(1).tex
192 doc/$(1).tex: $$(D)/$(1).md doc/uptack.tex doc/footer.tex doc/version.tex | doc/
193 @$$(call E, pandoc: $$@)
194 $$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) $$< --output=$$@
196 ifneq ($(NO_PDF_DOCS),1)
197 ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
198 DOC_TARGETS += doc/$(1).pdf
200 doc/$(1).pdf: doc/$(1).tex
201 @$$(call E, latex compiler: $$@)
203 -interaction=batchmode \
204 -output-directory=doc \
207 # The version of xelatex on the snap bots seemingly ingores -output-directory
208 # So we'll output to . and move to the doc directory manually.
209 # This will leave some intermediate files in the build directory.
210 doc/$(1).pdf: doc/$(1).tex
211 @$$(call E, latex compiler: $$@)
213 -interaction=batchmode \
214 -output-directory=. \
216 $$(Q)mv ./$(1).pdf $$@
218 endif # SHOULD_BUILD_PDF_DOCS_$(1)
221 endif # ONLY_HTML_DOCS
225 $(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
228 ######################################################################
229 # Rustdoc (libstd/extra)
230 ######################################################################
233 # The library documenting macro
235 # $(1) - The crate name (std/extra)
237 # Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
240 # If NO_REBUILD is set then break the dependencies on rustdoc so we
241 # build crate documentation without having to rebuild rustdoc.
242 ifeq ($(NO_REBUILD),)
247 $$(foreach dep,$$(RUST_DEPS_$(1)), \
248 $$(TLIB2_T_$(CFG_BUILD)_H_$(CFG_BUILD))/stamp.$$(dep)) \
249 $$(foreach dep,$$(filter $$(DOC_CRATES), $$(RUST_DEPS_$(1))), \
252 LIB_DOC_DEP_$(1) = $$(CRATEFILE_$(1)) $$(RSINPUTS_$(1))
258 doc/$(1)/index.html: CFG_COMPILER_HOST_TRIPLE = $(CFG_TARGET)
259 doc/$(1)/index.html: $$(LIB_DOC_DEP_$(1)) doc/$(1)/
260 @$$(call E, rustdoc: $$@)
261 $$(Q)CFG_LLVM_LINKAGE_FILE=$$(LLVM_LINKAGE_PATH_$(CFG_BUILD)) \
262 $$(RUSTDOC) --cfg dox --cfg stage2 $$(RUSTFLAGS_$(1)) $$<
265 $(foreach crate,$(CRATES),$(eval $(call DEF_LIB_DOC,$(crate))))
267 COMPILER_DOC_TARGETS := $(CRATES:%=doc/%/index.html)
268 ifdef CFG_ENABLE_COMPILER_DOCS
269 DOC_TARGETS += $(COMPILER_DOC_TARGETS)
271 DOC_TARGETS += $(DOC_CRATES:%=doc/%/index.html)
274 ifdef CFG_DISABLE_DOCS
275 $(info cfg: disabling doc build (CFG_DISABLE_DOCS))
277 COMPILER_DOC_TARGETS :=
281 compiler-docs: $(COMPILER_DOC_TARGETS)
283 trpl: doc/book/index.html
285 doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md) | doc/
286 @$(call E, rustbook: $@)
288 $(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book
290 nomicon: doc/nomicon/index.html
292 doc/nomicon/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/nomicon/*.md) | doc/
293 @$(call E, rustbook: $@)
294 $(Q)rm -rf doc/nomicon
295 $(Q)$(RUSTBOOK) build $(S)src/doc/nomicon doc/nomicon
297 style: doc/style/index.html
299 doc/style/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/style/*.md) | doc/
300 @$(call E, rustbook: $@)
302 $(Q)$(RUSTBOOK) build $(S)src/doc/style doc/style
304 error-index: doc/error-index.html
306 doc/error-index.html: $(ERR_IDX_GEN_EXE) | doc/
307 $(Q)$(call E, error-index-generator: $@)