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 # RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
17 # rustdoc invocation for xyz.
19 # RUSTDOC_DEPS_xyz are extra dependencies for the rustdoc invocation
22 # L10N_LANGS are the languages for which the docs have been
24 ######################################################################
25 DOCS := index intro tutorial \
26 complement-lang-faq complement-design-faq complement-project-faq \
27 rustdoc reference grammar
29 # Legacy guides, preserved for a while to reduce the number of 404s
30 DOCS += guide-crates guide-error-handling guide-ffi guide-macros guide \
31 guide-ownership guide-plugins guide-pointers guide-strings guide-tasks \
35 RUSTDOC_DEPS_reference := doc/full-toc.inc
36 RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
40 # Generally no need to edit below here.
42 # The options are passed to the documentation generators.
43 RUSTDOC_HTML_OPTS_NO_CSS = --html-before-content=doc/version_info.html \
44 --html-in-header=doc/favicon.inc \
45 --html-after-content=doc/footer.inc \
46 --markdown-playground-url='http://play.rust-lang.org/'
48 RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
50 # The rustdoc executable...
51 RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
52 # ...with rpath included in case --disable-rpath was provided to
54 RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
56 # The rustbook executable...
57 RUSTBOOK_EXE = $(HBIN2_H_$(CFG_BUILD))/rustbook$(X_$(CFG_BUILD))
58 # ...with rpath included in case --disable-rpath was provided to
60 RUSTBOOK = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTBOOK_EXE)
62 # The error-index-generator executable...
63 ERR_IDX_GEN_EXE = $(HBIN2_H_$(CFG_BUILD))/error-index-generator$(X_$(CFG_BUILD))
64 ERR_IDX_GEN = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(ERR_IDX_GEN_EXE)
68 DOC_TARGETS := trpl nomicon style error-index
69 COMPILER_DOC_TARGETS :=
72 # If NO_REBUILD is set then break the dependencies on rustdoc so we
73 # build the documentation without having to rebuild rustdoc.
75 HTML_DEPS := $(RUSTDOC_EXE)
80 ######################################################################
82 ######################################################################
84 HTML_DEPS += doc/version_info.html
85 doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
86 $(wildcard $(D)/*.*) | doc/
87 @$(call E, version-info: $@)
88 $(Q)sed -e "s/VERSION/$(CFG_RELEASE)/; \
89 s/SHORT_HASH/$(CFG_SHORT_VER_HASH)/; \
90 s/STAMP/$(CFG_VER_HASH)/;" $< >$@
92 GENERATED += doc/version_info.html
94 ######################################################################
96 ######################################################################
101 HTML_DEPS += doc/rust.css
102 doc/rust.css: $(D)/rust.css | doc/
104 $(Q)cp -PRp $< $@ 2> /dev/null
106 HTML_DEPS += doc/favicon.inc
107 doc/favicon.inc: $(D)/favicon.inc | doc/
109 $(Q)cp -PRp $< $@ 2> /dev/null
111 doc/full-toc.inc: $(D)/full-toc.inc | doc/
113 $(Q)cp -PRp $< $@ 2> /dev/null
115 HTML_DEPS += doc/footer.inc
116 doc/footer.inc: $(D)/footer.inc | doc/
118 $(Q)cp -PRp $< $@ 2> /dev/null
120 # The (english) documentation for each doc item.
121 DOC_TARGETS += doc/not_found.html
122 doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
123 @$(call E, rustdoc: $@)
124 $(Q)$(RUSTDOC) $(RUSTDOC_HTML_OPTS_NO_CSS) \
126 --markdown-css http://doc.rust-lang.org/rust.css $<
131 DOC_TARGETS += doc/$(1).html
132 doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
133 @$$(call E, rustdoc: $$@)
134 $$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
138 $(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
141 ######################################################################
142 # Rustdoc (libstd/extra)
143 ######################################################################
146 # The library documenting macro
148 # $(1) - The crate name (std/extra)
150 # Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
153 # If NO_REBUILD is set then break the dependencies on rustdoc so we
154 # build crate documentation without having to rebuild rustdoc.
155 ifeq ($(NO_REBUILD),)
160 $$(foreach dep,$$(RUST_DEPS_$(1)), \
161 $$(TLIB2_T_$(CFG_BUILD)_H_$(CFG_BUILD))/stamp.$$(dep)) \
162 $$(foreach dep,$$(filter $$(DOC_CRATES), $$(RUST_DEPS_$(1))), \
165 LIB_DOC_DEP_$(1) = $$(CRATEFILE_$(1)) $$(RSINPUTS_$(1))
171 doc/$(1)/index.html: CFG_COMPILER_HOST_TRIPLE = $(CFG_TARGET)
172 doc/$(1)/index.html: $$(LIB_DOC_DEP_$(1)) doc/$(1)/
173 @$$(call E, rustdoc: $$@)
174 $$(Q)CFG_LLVM_LINKAGE_FILE=$$(LLVM_LINKAGE_PATH_$(CFG_BUILD)) \
175 $$(RUSTDOC) --cfg dox --cfg stage2 $$(RUSTFLAGS_$(1)) $$<
178 $(foreach crate,$(CRATES),$(eval $(call DEF_LIB_DOC,$(crate))))
180 COMPILER_DOC_TARGETS := $(CRATES:%=doc/%/index.html)
181 ifdef CFG_ENABLE_COMPILER_DOCS
182 DOC_TARGETS += $(COMPILER_DOC_TARGETS)
184 DOC_TARGETS += $(DOC_CRATES:%=doc/%/index.html)
187 ifdef CFG_DISABLE_DOCS
188 $(info cfg: disabling doc build (CFG_DISABLE_DOCS))
190 COMPILER_DOC_TARGETS :=
194 compiler-docs: $(COMPILER_DOC_TARGETS)
196 trpl: doc/book/index.html
198 doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md) | doc/
199 @$(call E, rustbook: $@)
201 $(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book
203 nomicon: doc/nomicon/index.html
205 doc/nomicon/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/nomicon/*.md) | doc/
206 @$(call E, rustbook: $@)
207 $(Q)rm -rf doc/nomicon
208 $(Q)$(RUSTBOOK) build $(S)src/doc/nomicon doc/nomicon
210 style: doc/style/index.html
212 doc/style/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/style/*.md) | doc/
213 @$(call E, rustbook: $@)
215 $(Q)$(RUSTBOOK) build $(S)src/doc/style doc/style
217 error-index: doc/error-index.html
219 doc/error-index.html: $(ERR_IDX_GEN_EXE) | doc/
220 $(Q)$(call E, error-index-generator: $@)