mk/docs.mk

   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.
   4 #
   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.
  10
  11 ######################################################################
  12 # The various pieces of standalone documentation.
  13 #
  14 # The DOCS variable is their names (with no file extension).
  15 #
  16 # RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
  17 # rustdoc invocation for xyz.
  18 #
  19 # RUSTDOC_DEPS_xyz are extra dependencies for the rustdoc invocation
  20 # on xyz.
  21 #
  22 # L10N_LANGS are the languages for which the docs have been
  23 # translated.
  24 ######################################################################
  25 DOCS := index \
  26     complement-lang-faq complement-design-faq complement-project-faq \
  27     rustdoc reference grammar
  28
  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
  33
  34
  35 RUSTDOC_DEPS_reference := doc/full-toc.inc
  36 RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
  37
  38 L10N_LANGS := ja
  39
  40 # Generally no need to edit below here.
  41
  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/'
  47
  48 RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
  49
  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
  53 # ./configure
  54 RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
  55
  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
  59 # ./configure
  60 RUSTBOOK = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTBOOK_EXE)
  61
  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)
  65 ERR_IDX_GEN_MD = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(ERR_IDX_GEN_EXE) markdown
  66
  67 D := $(S)src/doc
  68
  69 DOC_TARGETS := book nomicon style error-index
  70 COMPILER_DOC_TARGETS :=
  71 DOC_L10N_TARGETS :=
  72
  73 # If NO_REBUILD is set then break the dependencies on rustdoc so we
  74 # build the documentation without having to rebuild rustdoc.
  75 ifeq ($(NO_REBUILD),)
  76 HTML_DEPS := $(RUSTDOC_EXE)
  77 else
  78 HTML_DEPS :=
  79 endif
  80
  81 ######################################################################
  82 # Rust version
  83 ######################################################################
  84
  85 HTML_DEPS += doc/version_info.html
  86 doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
  87                        $(wildcard $(D)/*.*) | doc/
  88         @$(call E, version-info: $@)
  89         $(Q)sed -e "s/VERSION/$(CFG_RELEASE)/; \
  90                 s/SHORT_HASH/$(CFG_SHORT_VER_HASH)/; \
  91                 s/STAMP/$(CFG_VER_HASH)/;" $< >$@
  92
  93 GENERATED += doc/version_info.html
  94
  95 ######################################################################
  96 # Docs from rustdoc
  97 ######################################################################
  98
  99 doc/:
 100         @mkdir -p $@
 101
 102 HTML_DEPS += doc/rust.css
 103 doc/rust.css: $(D)/rust.css | doc/
 104         @$(call E, cp: $@)
 105         $(Q)cp -PRp $< $@ 2> /dev/null
 106
 107 HTML_DEPS += doc/favicon.inc
 108 doc/favicon.inc: $(D)/favicon.inc | doc/
 109         @$(call E, cp: $@)
 110         $(Q)cp -PRp $< $@ 2> /dev/null
 111
 112 doc/full-toc.inc: $(D)/full-toc.inc | doc/
 113         @$(call E, cp: $@)
 114         $(Q)cp -PRp $< $@ 2> /dev/null
 115
 116 HTML_DEPS += doc/footer.inc
 117 doc/footer.inc: $(D)/footer.inc | doc/
 118         @$(call E, cp: $@)
 119         $(Q)cp -PRp $< $@ 2> /dev/null
 120
 121 # The (english) documentation for each doc item.
 122 DOC_TARGETS += doc/not_found.html
 123 doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
 124         @$(call E, rustdoc: $@)
 125         $(Q)$(RUSTDOC) $(RUSTDOC_HTML_OPTS_NO_CSS) \
 126                 --markdown-no-toc \
 127                 --markdown-css https://doc.rust-lang.org/rust.css $<
 128
 129 define DEF_DOC
 130
 131 # HTML (rustdoc)
 132 DOC_TARGETS += doc/$(1).html
 133 doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
 134         @$$(call E, rustdoc: $$@)
 135         $$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
 136
 137 endef
 138
 139 $(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
 140
 141
 142 ######################################################################
 143 # Rustdoc (libstd/extra)
 144 ######################################################################
 145
 146
 147 # The library documenting macro
 148 #
 149 # $(1) - The crate name (std/extra)
 150 #
 151 # Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
 152 define DEF_LIB_DOC
 153
 154 # If NO_REBUILD is set then break the dependencies on rustdoc so we
 155 # build crate documentation without having to rebuild rustdoc.
 156 ifeq ($(NO_REBUILD),)
 157 LIB_DOC_DEP_$(1) = \
 158         $$(CRATEFILE_$(1)) \
 159         $$(RSINPUTS_$(1)) \
 160         $$(RUSTDOC_EXE) \
 161         $$(foreach dep,$$(RUST_DEPS_$(1)), \
 162                 $$(TLIB2_T_$(CFG_BUILD)_H_$(CFG_BUILD))/stamp.$$(dep)) \
 163         $$(foreach dep,$$(filter $$(DOC_CRATES), $$(RUST_DEPS_$(1))), \
 164                 doc/$$(dep)/)
 165 else
 166 LIB_DOC_DEP_$(1) = $$(CRATEFILE_$(1)) $$(RSINPUTS_$(1))
 167 endif
 168
 169 doc/$(1)/:
 170         $$(Q)mkdir -p $$@
 171
 172 doc/$(1)/index.html: CFG_COMPILER_HOST_TRIPLE = $(CFG_TARGET)
 173 doc/$(1)/index.html: $$(LIB_DOC_DEP_$(1)) doc/$(1)/
 174         @$$(call E, rustdoc: $$@)
 175         $$(Q)CFG_LLVM_LINKAGE_FILE=$$(LLVM_LINKAGE_PATH_$(CFG_BUILD)) \
 176                 $$(RUSTDOC) --cfg dox --cfg stage2 $$(RUSTFLAGS_$(1)) $$<
 177 endef
 178
 179 $(foreach crate,$(CRATES),$(eval $(call DEF_LIB_DOC,$(crate))))
 180
 181 COMPILER_DOC_TARGETS := $(CRATES:%=doc/%/index.html)
 182 ifdef CFG_ENABLE_COMPILER_DOCS
 183   DOC_TARGETS += $(COMPILER_DOC_TARGETS)
 184 else
 185   DOC_TARGETS += $(DOC_CRATES:%=doc/%/index.html)
 186 endif
 187
 188 ifdef CFG_DISABLE_DOCS
 189   $(info cfg: disabling doc build (CFG_DISABLE_DOCS))
 190   DOC_TARGETS :=
 191   COMPILER_DOC_TARGETS :=
 192 endif
 193
 194 docs: $(DOC_TARGETS)
 195 doc: docs
 196 compiler-docs: $(COMPILER_DOC_TARGETS)
 197
 198 book: doc/book/index.html
 199
 200 doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/book/*.md) | doc/
 201         @$(call E, rustbook: $@)
 202         $(Q)rm -rf doc/book
 203         $(Q)$(RUSTBOOK) build $(S)src/doc/book doc/book
 204
 205 nomicon: doc/nomicon/index.html
 206
 207 doc/nomicon/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/nomicon/*.md) | doc/
 208         @$(call E, rustbook: $@)
 209         $(Q)rm -rf doc/nomicon
 210         $(Q)$(RUSTBOOK) build $(S)src/doc/nomicon doc/nomicon
 211
 212 style: doc/style/index.html
 213
 214 doc/style/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/style/*.md) | doc/
 215         @$(call E, rustbook: $@)
 216         $(Q)rm -rf doc/style
 217         $(Q)$(RUSTBOOK) build $(S)src/doc/style doc/style
 218
 219 error-index: doc/error-index.html
 220
 221 # Metadata used to generate the index is created as a side effect of
 222 # the build so this depends on every crate being up to date.
 223 doc/error-index.html: $(ERR_IDX_GEN_EXE) $(CSREQ$(2)_T_$(CFG_BUILD)_H_$(CFG_BUILD)) | doc/
 224         $(Q)$(call E, error_index_generator: $@)
 225         $(Q)$(ERR_IDX_GEN)
 226
 227 doc/error-index.md: $(ERR_IDX_GEN_EXE) $(CSREQ$(2)_T_$(CFG_BUILD)_H_$(CFG_BUILD)) | doc/
 228         $(Q)$(call E, error_index_generator: $@)
 229         $(Q)$(ERR_IDX_GEN_MD)