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, tutorial,
  13 # manual etc.
  14 #
  15 # The DOCS variable is their names (with no file extension).
  16 #
  17 # PDF_DOCS lists the targets for which PDF documentation should be
  18 # build.
  19 #
  20 # RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
  21 # rustdoc invocation for xyz.
  22 #
  23 # RUSTDOC_DEPS_xyz are extra dependencies for the rustdoc invocation
  24 # on xyz.
  25 #
  26 # L10N_LANGS are the languages for which the docs have been
  27 # translated.
  28 ######################################################################
  29 DOCS := index intro tutorial guide-ffi guide-macros guide-lifetimes \
  30         guide-tasks guide-container guide-pointers guide-testing \
  31         guide-runtime complement-bugreport complement-cheatsheet \
  32         complement-lang-faq complement-project-faq rust rustdoc \
  33         guide-unsafe
  34
  35 PDF_DOCS := tutorial rust
  36
  37 RUSTDOC_DEPS_rust := doc/full-toc.inc
  38 RUSTDOC_FLAGS_rust := --markdown-in-header=doc/full-toc.inc
  39
  40 L10N_LANGS := ja
  41
  42 # Generally no need to edit below here.
  43
  44 # The options are passed to the documentation generators.
  45 RUSTDOC_HTML_OPTS = --markdown-css rust.css \
  46         --markdown-before-content=doc/version_info.html \
  47         --markdown-in-header=doc/favicon.inc --markdown-after-content=doc/footer.inc
  48
  49 PANDOC_BASE_OPTS := --standalone --toc --number-sections
  50 PANDOC_TEX_OPTS = $(PANDOC_BASE_OPTS) --include-before-body=doc/version.tex \
  51         --from=markdown --include-before-body=doc/footer.tex --to=latex
  52 PANDOC_EPUB_OPTS = $(PANDOC_BASE_OPTS) --to=epub
  53
  54 # The rustdoc executable...
  55 RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
  56 # ...with rpath included in case --disable-rpath was provided to
  57 # ./configure
  58 RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
  59
  60 D := $(S)src/doc
  61
  62 DOC_TARGETS :=
  63 COMPILER_DOC_TARGETS :=
  64 DOC_L10N_TARGETS :=
  65
  66 # If NO_REBUILD is set then break the dependencies on rustdoc so we
  67 # build the documentation without having to rebuild rustdoc.
  68 ifeq ($(NO_REBUILD),)
  69 HTML_DEPS := $(RUSTDOC_EXE)
  70 else
  71 HTML_DEPS :=
  72 endif
  73
  74 # Check for the various external utilities for the EPUB/PDF docs:
  75
  76 ifeq ($(CFG_PDFLATEX),)
  77   $(info cfg: no pdflatex found, deferring to xelatex)
  78   ifeq ($(CFG_XELATEX),)
  79     $(info cfg: no xelatex found, deferring to lualatex)
  80     ifeq ($(CFG_LUALATEX),)
  81       $(info cfg: no lualatex found, disabling LaTeX docs)
  82       NO_PDF_DOCS = 1
  83         else
  84       CFG_LATEX := $(CFG_LUALATEX)
  85     endif
  86   else
  87     CFG_LATEX := $(CFG_XELATEX)
  88   endif
  89 else
  90   CFG_LATEX := $(CFG_PDFLATEX)
  91 endif
  92
  93
  94 ifeq ($(CFG_PANDOC),)
  95 $(info cfg: no pandoc found, omitting PDF and EPUB docs)
  96 ONLY_HTML_DOCS = 1
  97 endif
  98
  99
 100 ######################################################################
 101 # Rust version
 102 ######################################################################
 103
 104 doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
 105         @$(call E, version-stamp: $@)
 106         $(Q)echo "$(CFG_VERSION)" >$@
 107
 108 HTML_DEPS += doc/version_info.html
 109 doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
 110                        $(wildcard $(D)/*.*) | doc/
 111         @$(call E, version-info: $@)
 112         sed -e "s/VERSION/$(CFG_RELEASE)/; s/SHORT_HASH/$(shell echo \
 113                     $(CFG_VER_HASH) | head -c 8)/;\
 114                 s/STAMP/$(CFG_VER_HASH)/;" $< >$@
 115
 116 GENERATED += doc/version.tex doc/version_info.html
 117
 118 ######################################################################
 119 # Docs, from rustdoc and sometimes pandoc
 120 ######################################################################
 121
 122 doc/:
 123         @mkdir -p $@
 124
 125 HTML_DEPS += doc/rust.css
 126 doc/rust.css: $(D)/rust.css | doc/
 127         @$(call E, cp: $@)
 128         $(Q)cp -a $< $@ 2> /dev/null
 129
 130 HTML_DEPS += doc/favicon.inc
 131 doc/favicon.inc: $(D)/favicon.inc | doc/
 132         @$(call E, cp: $@)
 133         $(Q)cp -a $< $@ 2> /dev/null
 134
 135 doc/full-toc.inc: $(D)/full-toc.inc | doc/
 136         @$(call E, cp: $@)
 137         $(Q)cp -a $< $@ 2> /dev/null
 138
 139 HTML_DEPS += doc/footer.inc
 140 doc/footer.inc: $(D)/footer.inc | doc/
 141         @$(call E, cp: $@)
 142         $(Q)cp -a $< $@ 2> /dev/null
 143
 144 doc/FiraSans-Regular.woff: $(D)/FiraSans-Regular.woff | doc/
 145         @$(call E, cp: $@)
 146         $(Q)cp -a $< $@ 2> /dev/null
 147
 148 doc/FiraSans-Medium.woff: $(D)/FiraSans-Medium.woff | doc/
 149         @$(call E, cp: $@)
 150         $(Q)cp -a $< $@ 2> /dev/null
 151
 152 doc/Heuristica-Regular.woff: $(D)/Heuristica-Regular.woff | doc/
 153         @$(call E, cp: $@)
 154         $(Q)cp -a $< $@ 2> /dev/null
 155
 156 doc/Heuristica-Italic.woff: $(D)/Heuristica-Italic.woff | doc/
 157         @$(call E, cp: $@)
 158         $(Q)cp -a $< $@ 2> /dev/null
 159
 160 doc/Heuristica-Bold.woff: $(D)/Heuristica-Bold.woff | doc/
 161         @$(call E, cp: $@)
 162         $(Q)cp -a $< $@ 2> /dev/null
 163
 164 # The (english) documentation for each doc item.
 165
 166 define DEF_SHOULD_BUILD_PDF_DOC
 167 SHOULD_BUILD_PDF_DOC_$(1) = 1
 168 endef
 169 $(foreach docname,$(PDF_DOCS),$(eval $(call DEF_SHOULD_BUILD_PDF_DOC,$(docname))))
 170
 171 doc/footer.tex: $(D)/footer.inc | doc/
 172         @$(call E, pandoc: $@)
 173         $(CFG_PANDOC) --from=html --to=latex $< --output=$@
 174
 175 define DEF_DOC
 176
 177 # HTML (rustdoc)
 178 DOC_TARGETS += doc/$(1).html
 179 doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
 180         @$$(call E, rustdoc: $$@)
 181         $$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
 182
 183 ifneq ($(ONLY_HTML_DOCS),1)
 184
 185 # EPUB (pandoc directly)
 186 DOC_TARGETS += doc/$(1).epub
 187 doc/$(1).epub: $$(D)/$(1).md | doc/
 188         @$$(call E, pandoc: $$@)
 189         $$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) $$< --output=$$@
 190
 191 # PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
 192 DOC_TARGETS += doc/$(1).tex
 193 doc/$(1).tex: $$(D)/$(1).md doc/footer.tex doc/version.tex | doc/
 194         @$$(call E, pandoc: $$@)
 195         $$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) $$< --output=$$@
 196
 197 ifneq ($(NO_PDF_DOCS),1)
 198 ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
 199 DOC_TARGETS += doc/$(1).pdf
 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 endif # SHOULD_BUILD_PDF_DOCS_$(1)
 207 endif # NO_PDF_DOCS
 208
 209 endif # ONLY_HTML_DOCS
 210
 211 endef
 212
 213 $(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
 214
 215
 216 # Localized documentation
 217
 218 # FIXME: I (huonw) haven't actually been able to test properly, since
 219 # e.g. (by default) I'm doing an out-of-tree build (#12763), but even
 220 # adjusting for that, the files are too old(?) and are rejected by
 221 # po4a.
 222 #
 223 # As such, I've attempted to get it working as much as possible (and
 224 # switching from pandoc to rustdoc), but preserving the old behaviour
 225 # (e.g. only running on the tutorial)
 226 .PHONY: l10n-mds
 227 l10n-mds: $(D)/po4a.conf \
 228                 $(foreach lang,$(L10N_LANG),$(D)/po/$(lang)/*.md.po)
 229         $(warning WARNING: localized documentation is experimental)
 230         po4a --copyright-holder="The Rust Project Developers" \
 231                 --package-name="Rust" \
 232                 --package-version="$(CFG_RELEASE)" \
 233                 -M UTF-8 -L UTF-8 \
 234                 $(D)/po4a.conf
 235
 236 define DEF_L10N_DOC
 237 DOC_L10N_TARGETS += doc/l10n/$(1)/$(2).html
 238 doc/l10n/$(1)/$(2).html: l10n-mds $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(2))
 239         @$$(call E, rustdoc: $$@)
 240         $$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) doc/l10n/$(1)/$(2).md
 241 endef
 242
 243 $(foreach lang,$(L10N_LANGS),$(eval $(call DEF_L10N_DOC,$(lang),tutorial)))
 244
 245
 246 ######################################################################
 247 # LLnextgen (grammar analysis from refman)
 248 ######################################################################
 249
 250 ifeq ($(CFG_LLNEXTGEN),)
 251   $(info cfg: no llnextgen found, omitting grammar-verification)
 252 else
 253 .PHONY: verify-grammar
 254
 255 doc/rust.g: $(D)/rust.md $(S)src/etc/extract_grammar.py
 256         @$(call E, extract_grammar: $@)
 257         $(Q)$(CFG_PYTHON) $(S)src/etc/extract_grammar.py $< >$@
 258
 259 verify-grammar: doc/rust.g
 260         @$(call E, LLnextgen: $<)
 261         $(Q)$(CFG_LLNEXTGEN) --generate-lexer-wrapper=no $< >$@
 262         $(Q)rm -f doc/rust.c doc/rust.h
 263 endif
 264
 265
 266 ######################################################################
 267 # Rustdoc (libstd/extra)
 268 ######################################################################
 269
 270
 271 # The library documenting macro
 272 #
 273 # $(1) - The crate name (std/extra)
 274 #
 275 # Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
 276 define DEF_LIB_DOC
 277
 278 # If NO_REBUILD is set then break the dependencies on rustdoc so we
 279 # build crate documentation without having to rebuild rustdoc.
 280 ifeq ($(NO_REBUILD),)
 281 LIB_DOC_DEP_$(1) = \
 282         $$(CRATEFILE_$(1)) \
 283         $$(RSINPUTS_$(1)) \
 284         $$(RUSTDOC_EXE) \
 285         $$(foreach dep,$$(RUST_DEPS_$(1)), \
 286                 $$(TLIB2_T_$(CFG_BUILD)_H_$(CFG_BUILD))/stamp.$$(dep))
 287 else
 288 LIB_DOC_DEP_$(1) = $$(CRATEFILE_$(1)) $$(RSINPUTS_$(1))
 289 endif
 290
 291 $(2) += doc/$(1)/index.html
 292 doc/$(1)/index.html: CFG_COMPILER_HOST_TRIPLE = $(CFG_TARGET)
 293 doc/$(1)/index.html: $$(LIB_DOC_DEP_$(1))
 294         @$$(call E, rustdoc $$@)
 295         $$(Q)$$(RUSTDOC) --cfg dox --cfg stage2 $$<
 296 endef
 297
 298 $(foreach crate,$(DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),DOC_TARGETS)))
 299 $(foreach crate,$(COMPILER_DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),COMPILER_DOC_TARGETS)))
 300
 301 ifdef CFG_DISABLE_DOCS
 302   $(info cfg: disabling doc build (CFG_DISABLE_DOCS))
 303   DOC_TARGETS :=
 304 endif
 305
 306 docs: $(DOC_TARGETS)
 307 compiler-docs: $(COMPILER_DOC_TARGETS)
 308
 309 docs-l10n: $(DOC_L10N_TARGETS)
 310
 311 .PHONY: docs-l10n