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 # PDF_DOCS lists the targets for which PDF documentation should be
  17 # build.
  18 #
  19 # RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
  20 # rustdoc invocation for xyz.
  21 #
  22 # RUSTDOC_DEPS_xyz are extra dependencies for the rustdoc invocation
  23 # on xyz.
  24 #
  25 # L10N_LANGS are the languages for which the docs have been
  26 # translated.
  27 ######################################################################
  28 DOCS := index intro tutorial \
  29     complement-lang-faq complement-design-faq complement-project-faq \
  30     rustdoc reference grammar
  31
  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 \
  35     guide-testing
  36
  37
  38 PDF_DOCS := reference
  39
  40 RUSTDOC_DEPS_reference := doc/full-toc.inc
  41 RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
  42
  43 L10N_LANGS := ja
  44
  45 # Generally no need to edit below here.
  46
  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/'
  52
  53 RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
  54
  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
  61
  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
  65 # ./configure
  66 RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
  67
  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
  71 # ./configure
  72 RUSTBOOK = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTBOOK_EXE)
  73
  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)
  77
  78 D := $(S)src/doc
  79
  80 DOC_TARGETS := trpl nomicon style error-index
  81 COMPILER_DOC_TARGETS :=
  82 DOC_L10N_TARGETS :=
  83
  84 # If NO_REBUILD is set then break the dependencies on rustdoc so we
  85 # build the documentation without having to rebuild rustdoc.
  86 ifeq ($(NO_REBUILD),)
  87 HTML_DEPS := $(RUSTDOC_EXE)
  88 else
  89 HTML_DEPS :=
  90 endif
  91
  92 # Check for xelatex
  93
  94 ifneq ($(CFG_XELATEX),)
  95     CFG_LATEX := $(CFG_XELATEX)
  96     XELATEX = 1
  97   else
  98     $(info cfg: no xelatex found, disabling LaTeX docs)
  99     NO_PDF_DOCS = 1
 100 endif
 101
 102 ifeq ($(CFG_PANDOC),)
 103 $(info cfg: no pandoc found, omitting PDF and EPUB docs)
 104 ONLY_HTML_DOCS = 1
 105 endif
 106
 107
 108 ######################################################################
 109 # Rust version
 110 ######################################################################
 111
 112 doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
 113         @$(call E, version-stamp: $@)
 114         $(Q)echo "$(CFG_VERSION)" >$@
 115
 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)/;" $< >$@
 123
 124 GENERATED += doc/version.tex doc/version_info.html
 125
 126 ######################################################################
 127 # Docs, from rustdoc and sometimes pandoc
 128 ######################################################################
 129
 130 doc/:
 131         @mkdir -p $@
 132
 133 HTML_DEPS += doc/rust.css
 134 doc/rust.css: $(D)/rust.css | doc/
 135         @$(call E, cp: $@)
 136         $(Q)cp -PRp $< $@ 2> /dev/null
 137
 138 HTML_DEPS += doc/favicon.inc
 139 doc/favicon.inc: $(D)/favicon.inc | doc/
 140         @$(call E, cp: $@)
 141         $(Q)cp -PRp $< $@ 2> /dev/null
 142
 143 doc/full-toc.inc: $(D)/full-toc.inc | doc/
 144         @$(call E, cp: $@)
 145         $(Q)cp -PRp $< $@ 2> /dev/null
 146
 147 HTML_DEPS += doc/footer.inc
 148 doc/footer.inc: $(D)/footer.inc | doc/
 149         @$(call E, cp: $@)
 150         $(Q)cp -PRp $< $@ 2> /dev/null
 151
 152 # The (english) documentation for each doc item.
 153
 154 define DEF_SHOULD_BUILD_PDF_DOC
 155 SHOULD_BUILD_PDF_DOC_$(1) = 1
 156 endef
 157 $(foreach docname,$(PDF_DOCS),$(eval $(call DEF_SHOULD_BUILD_PDF_DOC,$(docname))))
 158
 159 doc/footer.tex: $(D)/footer.inc | doc/
 160         @$(call E, pandoc: $@)
 161         $(CFG_PANDOC) --from=html --to=latex $< --output=$@
 162
 163 doc/uptack.tex: $(D)/uptack.tex | doc/
 164         $(Q)cp $< $@
 165
 166 # HTML (rustdoc)
 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-no-toc \
 172                 --markdown-css http://doc.rust-lang.org/rust.css $<
 173
 174 define DEF_DOC
 175
 176 # HTML (rustdoc)
 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)) $$<
 181
 182 ifneq ($(ONLY_HTML_DOCS),1)
 183
 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=$$@
 189
 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=$$@
 195
 196 ifneq ($(NO_PDF_DOCS),1)
 197 ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
 198 DOC_TARGETS += doc/$(1).pdf
 199 ifneq ($(XELATEX),1)
 200 doc/$(1).pdf: doc/$(1).tex
 201         @$$(call E, latex compiler: $$@)
 202         $$(Q)$$(CFG_LATEX) \
 203         -interaction=batchmode \
 204         -output-directory=doc \
 205         $$<
 206 else
 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: $$@)
 212         $$(Q)$$(CFG_LATEX) \
 213         -interaction=batchmode \
 214         -output-directory=. \
 215         $$<
 216         $$(Q)mv ./$(1).pdf $$@
 217 endif # XELATEX
 218 endif # SHOULD_BUILD_PDF_DOCS_$(1)
 219 endif # NO_PDF_DOCS
 220
 221 endif # ONLY_HTML_DOCS
 222
 223 endef
 224
 225 $(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
 226
 227
 228 ######################################################################
 229 # Rustdoc (libstd/extra)
 230 ######################################################################
 231
 232
 233 # The library documenting macro
 234 #
 235 # $(1) - The crate name (std/extra)
 236 #
 237 # Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
 238 define DEF_LIB_DOC
 239
 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),)
 243 LIB_DOC_DEP_$(1) = \
 244         $$(CRATEFILE_$(1)) \
 245         $$(RSINPUTS_$(1)) \
 246         $$(RUSTDOC_EXE) \
 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))), \
 250                 doc/$$(dep)/)
 251 else
 252 LIB_DOC_DEP_$(1) = $$(CRATEFILE_$(1)) $$(RSINPUTS_$(1))
 253 endif
 254
 255 doc/$(1)/:
 256         $$(Q)mkdir -p $$@
 257
 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)) $$<
 263 endef
 264
 265 $(foreach crate,$(CRATES),$(eval $(call DEF_LIB_DOC,$(crate))))
 266
 267 COMPILER_DOC_TARGETS := $(CRATES:%=doc/%/index.html)
 268 ifdef CFG_ENABLE_COMPILER_DOCS
 269   DOC_TARGETS += $(COMPILER_DOC_TARGETS)
 270 else
 271   DOC_TARGETS += $(DOC_CRATES:%=doc/%/index.html)
 272 endif
 273
 274 ifdef CFG_DISABLE_DOCS
 275   $(info cfg: disabling doc build (CFG_DISABLE_DOCS))
 276   DOC_TARGETS :=
 277   COMPILER_DOC_TARGETS :=
 278 endif
 279
 280 docs: $(DOC_TARGETS)
 281 compiler-docs: $(COMPILER_DOC_TARGETS)
 282
 283 trpl: doc/book/index.html
 284
 285 doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md) | doc/
 286         @$(call E, rustbook: $@)
 287         $(Q)rm -rf doc/book
 288         $(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book
 289
 290 nomicon: doc/nomicon/index.html
 291
 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
 296
 297 style: doc/style/index.html
 298
 299 doc/style/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/style/*.md) | doc/
 300         @$(call E, rustbook: $@)
 301         $(Q)rm -rf doc/style
 302         $(Q)$(RUSTBOOK) build $(S)src/doc/style doc/style
 303
 304 error-index: doc/error-index.html
 305
 306 doc/error-index.html: $(ERR_IDX_GEN_EXE) | doc/
 307         $(Q)$(call E, error-index-generator: $@)
 308         $(Q)$(ERR_IDX_GEN)