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
='http://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 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
) \
171 --markdown-css http
://doc.rust-lang.org
/rust.css
$<
176 DOC_TARGETS
+= doc
/$(1).html
177 doc
/$(1).html
: $$(D
)/$(1).md
$$(HTML_DEPS
) $$(RUSTDOC_DEPS_
$(1)) | doc
/
178 @
$$(call E
, rustdoc
: $$@
)
179 $$(Q
)$$(RUSTDOC
) $$(RUSTDOC_HTML_OPTS
) $$(RUSTDOC_FLAGS_
$(1)) $$<
181 ifneq ($(ONLY_HTML_DOCS
),1)
183 # EPUB (pandoc directly)
184 DOC_TARGETS
+= doc
/$(1).epub
185 doc
/$(1).epub
: $$(D
)/$(1).md | doc
/
186 @
$$(call E
, pandoc
: $$@
)
187 $$(CFG_PANDOC
) $$(PANDOC_EPUB_OPTS
) $$< --output
=$$@
189 # PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
190 DOC_TARGETS
+= doc
/$(1).
tex
191 doc
/$(1).
tex: $$(D
)/$(1).md doc
/uptack.
tex doc
/footer.
tex doc
/version.
tex | doc
/
192 @
$$(call E
, pandoc
: $$@
)
193 $$(CFG_PANDOC
) $$(PANDOC_TEX_OPTS
) $$< --output
=$$@
195 ifneq ($(NO_PDF_DOCS
),1)
196 ifeq ($$(SHOULD_BUILD_PDF_DOC_
$(1)),1)
197 DOC_TARGETS
+= doc
/$(1).pdf
199 doc
/$(1).pdf
: doc
/$(1).
tex
200 @
$$(call E
, latex compiler
: $$@
)
202 -interaction
=batchmode \
203 -output-directory
=doc \
206 # The version of xelatex on the snap bots seemingly ingores -output-directory
207 # So we'll output to . and move to the doc directory manually.
208 # This will leave some intermediate files in the build directory.
209 doc
/$(1).pdf
: doc
/$(1).
tex
210 @
$$(call E
, latex compiler
: $$@
)
212 -interaction
=batchmode \
213 -output-directory
=. \
215 $$(Q
)mv .
/$(1).pdf
$$@
217 endif # SHOULD_BUILD_PDF_DOCS_$(1)
220 endif # ONLY_HTML_DOCS
224 $(foreach docname
,$(DOCS
),$(eval
$(call DEF_DOC
,$(docname
))))
227 ######################################################################
228 # Rustdoc (libstd/extra)
229 ######################################################################
232 # The library documenting macro
234 # $(1) - The crate name (std/extra)
236 # Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
239 # If NO_REBUILD is set then break the dependencies on rustdoc so we
240 # build crate documentation without having to rebuild rustdoc.
241 ifeq ($(NO_REBUILD
),)
246 $$(foreach dep
,$$(RUST_DEPS_
$(1)), \
247 $$(TLIB2_T_
$(CFG_BUILD
)_H_
$(CFG_BUILD
))/stamp.
$$(dep
)) \
248 $$(foreach dep
,$$(filter $$(DOC_CRATES
), $$(RUST_DEPS_
$(1))), \
251 LIB_DOC_DEP_
$(1) = $$(CRATEFILE_
$(1)) $$(RSINPUTS_
$(1))
257 doc
/$(1)/index.html
: CFG_COMPILER_HOST_TRIPLE
= $(CFG_TARGET
)
258 doc
/$(1)/index.html
: $$(LIB_DOC_DEP_
$(1)) doc
/$(1)/
259 @
$$(call E
, rustdoc
: $$@
)
260 $$(Q
)CFG_LLVM_LINKAGE_FILE
=$$(LLVM_LINKAGE_PATH_
$(CFG_BUILD
)) \
261 $$(RUSTDOC
) --cfg dox
--cfg stage2
$$(RUSTFLAGS_
$(1)) $$<
264 $(foreach crate
,$(CRATES
),$(eval
$(call DEF_LIB_DOC
,$(crate
))))
266 COMPILER_DOC_TARGETS
:= $(CRATES
:%=doc
/%/index.html
)
267 ifdef CFG_COMPILER_DOCS
268 DOC_TARGETS
+= $(COMPILER_DOC_TARGETS
)
270 DOC_TARGETS
+= $(DOC_CRATES
:%=doc
/%/index.html
)
273 ifdef CFG_DISABLE_DOCS
274 $(info cfg
: disabling doc build
(CFG_DISABLE_DOCS
))
276 COMPILER_DOC_TARGETS
:=
280 compiler-docs
: $(COMPILER_DOC_TARGETS
)
282 trpl
: doc
/book
/index.html
284 doc
/book
/index.html
: $(RUSTBOOK_EXE
) $(wildcard $(S
)/src
/doc
/trpl
/*.md
) | doc
/
285 @
$(call E
, rustbook
: $@
)
287 $(Q
)$(RUSTBOOK
) build
$(S
)src
/doc
/trpl doc
/book
289 style
: doc
/style
/index.html
291 doc
/style
/index.html
: $(RUSTBOOK_EXE
) $(wildcard $(S
)/src
/doc
/style
/*.md
) | doc
/
292 @
$(call E
, rustbook
: $@
)
294 $(Q
)$(RUSTBOOK
) build
$(S
)src
/doc
/style doc
/style
296 error-index
: doc
/error-index.html
298 doc
/error-index.html
: $(ERR_IDX_GEN_EXE
) | doc
/
299 $(Q
)$(call E
, error-index-generator
: $@
)