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 ######################################################################
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 \
32 guide-testing tutorial intro
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
='https://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
:= book 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 https
://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
:=
195 compiler-docs
: $(COMPILER_DOC_TARGETS
)
197 book
: doc
/book
/index.html
199 doc
/book
/index.html
: $(RUSTBOOK_EXE
) $(wildcard $(S
)/src
/doc
/book
/*.md
) | doc
/
200 @
$(call E
, rustbook
: $@
)
202 $(Q
)$(RUSTBOOK
) build
$(S
)src
/doc
/book doc
/book
204 nomicon
: doc
/nomicon
/index.html
206 doc
/nomicon
/index.html
: $(RUSTBOOK_EXE
) $(wildcard $(S
)/src
/doc
/nomicon
/*.md
) | doc
/
207 @
$(call E
, rustbook
: $@
)
208 $(Q
)rm -rf doc
/nomicon
209 $(Q
)$(RUSTBOOK
) build
$(S
)src
/doc
/nomicon doc
/nomicon
211 style
: doc
/style
/index.html
213 doc
/style
/index.html
: $(RUSTBOOK_EXE
) $(wildcard $(S
)/src
/doc
/style
/*.md
) | doc
/
214 @
$(call E
, rustbook
: $@
)
216 $(Q
)$(RUSTBOOK
) build
$(S
)src
/doc
/style doc
/style
218 error-index
: doc
/error-index.html
220 doc
/error-index.html
: $(ERR_IDX_GEN_EXE
) | doc
/
221 $(Q
)$(call E
, error-index-generator
: $@
)