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: guides, manual, etc
  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 guide guide-ffi guide-macros guide-ownership \
  29         guide-tasks guide-container guide-pointers guide-testing \
  30         guide-plugin guide-crates complement-bugreport guide-error-handling \
  31         complement-lang-faq complement-design-faq complement-project-faq \
  32     rustdoc guide-unsafe guide-strings reference
  33
  34 PDF_DOCS := guide reference
  35
  36 RUSTDOC_DEPS_reference := doc/full-toc.inc
  37 RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
  38
  39 L10N_LANGS := ja
  40
  41 # Generally no need to edit below here.
  42
  43 # The options are passed to the documentation generators.
  44 RUSTDOC_HTML_OPTS_NO_CSS = --html-before-content=doc/version_info.html \
  45         --html-in-header=doc/favicon.inc \
  46         --html-after-content=doc/footer.inc \
  47         --markdown-playground-url='http://play.rust-lang.org/'
  48
  49 RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
  50
  51 PANDOC_BASE_OPTS := --standalone --toc --number-sections
  52 PANDOC_TEX_OPTS = $(PANDOC_BASE_OPTS) --from=markdown --to=latex \
  53         --include-before-body=doc/version.tex \
  54         --include-before-body=doc/footer.tex \
  55         --include-in-header=doc/uptack.tex
  56 PANDOC_EPUB_OPTS = $(PANDOC_BASE_OPTS) --to=epub
  57
  58 # The rustdoc executable...
  59 RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
  60 # ...with rpath included in case --disable-rpath was provided to
  61 # ./configure
  62 RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
  63
  64 D := $(S)src/doc
  65
  66 DOC_TARGETS :=
  67 COMPILER_DOC_TARGETS :=
  68 DOC_L10N_TARGETS :=
  69
  70 # If NO_REBUILD is set then break the dependencies on rustdoc so we
  71 # build the documentation without having to rebuild rustdoc.
  72 ifeq ($(NO_REBUILD),)
  73 HTML_DEPS := $(RUSTDOC_EXE)
  74 else
  75 HTML_DEPS :=
  76 endif
  77
  78 # Check for the various external utilities for the EPUB/PDF docs:
  79
  80 ifeq ($(CFG_LUALATEX),)
  81   $(info cfg: no lualatex found, deferring to xelatex)
  82   ifeq ($(CFG_XELATEX),)
  83     $(info cfg: no xelatex found, deferring to pdflatex)
  84     ifeq ($(CFG_PDFLATEX),)
  85       $(info cfg: no pdflatex found, disabling LaTeX docs)
  86       NO_PDF_DOCS = 1
  87         else
  88       CFG_LATEX := $(CFG_PDFLATEX)
  89     endif
  90   else
  91     CFG_LATEX := $(CFG_XELATEX)
  92     XELATEX = 1
  93   endif
  94 else
  95   CFG_LATEX := $(CFG_LUALATEX)
  96 endif
  97
  98
  99 ifeq ($(CFG_PANDOC),)
 100 $(info cfg: no pandoc found, omitting PDF and EPUB docs)
 101 ONLY_HTML_DOCS = 1
 102 endif
 103
 104
 105 ######################################################################
 106 # Rust version
 107 ######################################################################
 108
 109 doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
 110         @$(call E, version-stamp: $@)
 111         $(Q)echo "$(CFG_VERSION)" >$@
 112
 113 HTML_DEPS += doc/version_info.html
 114 doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
 115                        $(wildcard $(D)/*.*) | doc/
 116         @$(call E, version-info: $@)
 117         $(Q)sed -e "s/VERSION/$(CFG_RELEASE)/; \
 118                 s/SHORT_HASH/$(CFG_SHORT_VER_HASH)/; \
 119                 s/STAMP/$(CFG_VER_HASH)/;" $< >$@
 120
 121 GENERATED += doc/version.tex doc/version_info.html
 122
 123 ######################################################################
 124 # Docs, from rustdoc and sometimes pandoc
 125 ######################################################################
 126
 127 doc/:
 128         @mkdir -p $@
 129
 130 HTML_DEPS += doc/rust.css
 131 doc/rust.css: $(D)/rust.css | doc/
 132         @$(call E, cp: $@)
 133         $(Q)cp -a $< $@ 2> /dev/null
 134
 135 HTML_DEPS += doc/favicon.inc
 136 doc/favicon.inc: $(D)/favicon.inc | doc/
 137         @$(call E, cp: $@)
 138         $(Q)cp -a $< $@ 2> /dev/null
 139
 140 doc/full-toc.inc: $(D)/full-toc.inc | doc/
 141         @$(call E, cp: $@)
 142         $(Q)cp -a $< $@ 2> /dev/null
 143
 144 HTML_DEPS += doc/footer.inc
 145 doc/footer.inc: $(D)/footer.inc | doc/
 146         @$(call E, cp: $@)
 147         $(Q)cp -a $< $@ 2> /dev/null
 148
 149 # The (english) documentation for each doc item.
 150
 151 define DEF_SHOULD_BUILD_PDF_DOC
 152 SHOULD_BUILD_PDF_DOC_$(1) = 1
 153 endef
 154 $(foreach docname,$(PDF_DOCS),$(eval $(call DEF_SHOULD_BUILD_PDF_DOC,$(docname))))
 155
 156 doc/footer.tex: $(D)/footer.inc | doc/
 157         @$(call E, pandoc: $@)
 158         $(CFG_PANDOC) --from=html --to=latex $< --output=$@
 159
 160 doc/uptack.tex: $(D)/uptack.tex | doc/
 161         $(Q)cp $< $@
 162
 163 # HTML (rustdoc)
 164 DOC_TARGETS += doc/not_found.html
 165 doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
 166         @$(call E, rustdoc: $@)
 167         $(Q)$(RUSTDOC) $(RUSTDOC_HTML_OPTS_NO_CSS) \
 168                 --markdown-css http://doc.rust-lang.org/rust.css $<
 169
 170 define DEF_DOC
 171
 172 # HTML (rustdoc)
 173 DOC_TARGETS += doc/$(1).html
 174 doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
 175         @$$(call E, rustdoc: $$@)
 176         $$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
 177
 178 ifneq ($(ONLY_HTML_DOCS),1)
 179
 180 # EPUB (pandoc directly)
 181 DOC_TARGETS += doc/$(1).epub
 182 doc/$(1).epub: $$(D)/$(1).md | doc/
 183         @$$(call E, pandoc: $$@)
 184         $$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) $$< --output=$$@
 185
 186 # PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
 187 DOC_TARGETS += doc/$(1).tex
 188 doc/$(1).tex: $$(D)/$(1).md doc/uptack.tex doc/footer.tex doc/version.tex | doc/
 189         @$$(call E, pandoc: $$@)
 190         $$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) $$< --output=$$@
 191
 192 ifneq ($(NO_PDF_DOCS),1)
 193 ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
 194 DOC_TARGETS += doc/$(1).pdf
 195 ifneq ($(XELATEX),1)
 196 doc/$(1).pdf: doc/$(1).tex
 197         @$$(call E, latex compiler: $$@)
 198         $$(Q)$$(CFG_LATEX) \
 199         -interaction=batchmode \
 200         -output-directory=doc \
 201         $$<
 202 else
 203 # The version of xelatex on the snap bots seemingly ingores -output-directory
 204 # So we'll output to . and move to the doc directory manually.
 205 # This will leave some intermediate files in the build directory.
 206 doc/$(1).pdf: doc/$(1).tex
 207         @$$(call E, latex compiler: $$@)
 208         $$(Q)$$(CFG_LATEX) \
 209         -interaction=batchmode \
 210         -output-directory=. \
 211         $$<
 212         $$(Q)mv ./$(1).pdf $$@
 213 endif # XELATEX
 214 endif # SHOULD_BUILD_PDF_DOCS_$(1)
 215 endif # NO_PDF_DOCS
 216
 217 endif # ONLY_HTML_DOCS
 218
 219 endef
 220
 221 $(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
 222
 223
 224 ######################################################################
 225 # Rustdoc (libstd/extra)
 226 ######################################################################
 227
 228
 229 # The library documenting macro
 230 #
 231 # $(1) - The crate name (std/extra)
 232 #
 233 # Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
 234 define DEF_LIB_DOC
 235
 236 # If NO_REBUILD is set then break the dependencies on rustdoc so we
 237 # build crate documentation without having to rebuild rustdoc.
 238 ifeq ($(NO_REBUILD),)
 239 LIB_DOC_DEP_$(1) = \
 240         $$(CRATEFILE_$(1)) \
 241         $$(RSINPUTS_$(1)) \
 242         $$(RUSTDOC_EXE) \
 243         $$(foreach dep,$$(RUST_DEPS_$(1)), \
 244                 $$(TLIB2_T_$(CFG_BUILD)_H_$(CFG_BUILD))/stamp.$$(dep)) \
 245         $$(foreach dep,$$(filter $$(DOC_CRATES), $$(RUST_DEPS_$(1))), \
 246                 doc/$$(dep)/)
 247 else
 248 LIB_DOC_DEP_$(1) = $$(CRATEFILE_$(1)) $$(RSINPUTS_$(1))
 249 endif
 250
 251 doc/$(1)/:
 252         $$(Q)mkdir -p $$@
 253
 254 $(2) += doc/$(1)/index.html
 255 doc/$(1)/index.html: CFG_COMPILER_HOST_TRIPLE = $(CFG_TARGET)
 256 doc/$(1)/index.html: $$(LIB_DOC_DEP_$(1)) doc/$(1)/
 257         @$$(call E, rustdoc: $$@)
 258         $$(Q)CFG_LLVM_LINKAGE_FILE=$$(LLVM_LINKAGE_PATH_$(CFG_BUILD)) \
 259                 $$(RUSTDOC) --cfg dox --cfg stage2 $$<
 260 endef
 261
 262 $(foreach crate,$(DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),DOC_TARGETS)))
 263 $(foreach crate,$(COMPILER_DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),COMPILER_DOC_TARGETS)))
 264
 265 ifdef CFG_DISABLE_DOCS
 266   $(info cfg: disabling doc build (CFG_DISABLE_DOCS))
 267   DOC_TARGETS :=
 268   COMPILER_DOC_TARGETS :=
 269 endif
 270
 271 docs: $(DOC_TARGETS)
 272 compiler-docs: $(COMPILER_DOC_TARGETS)