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