Auto merge of #27789 - chriskrycho:remove_pandoc_references, r=steveklabnik
Per @steveklabnik's comment [here](https://github.com/rust-lang/cargo/issues/739#issuecomment-130085860), the Pandoc components of the Makefile are no longer used, and as such the corresponding components of the documentation are out of date. - I've removed the Pandoc (and therefore also LaTeX) elements of the makefile and confirmed that the build proceeds correctly. - I updated the documentation to reference `rustdoc` and of Pandoc. r? @steveklabnik
This commit is contained in:
commit
b2aef9d58b
91
mk/docs.mk
91
mk/docs.mk
|
@ -13,9 +13,6 @@
|
||||||
#
|
#
|
||||||
# The DOCS variable is their names (with no file extension).
|
# The DOCS variable is their names (with no file extension).
|
||||||
#
|
#
|
||||||
# PDF_DOCS lists the targets for which PDF documentation should be
|
|
||||||
# build.
|
|
||||||
#
|
|
||||||
# RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
|
# RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
|
||||||
# rustdoc invocation for xyz.
|
# rustdoc invocation for xyz.
|
||||||
#
|
#
|
||||||
|
@ -35,8 +32,6 @@ DOCS += guide-crates guide-error-handling guide-ffi guide-macros guide \
|
||||||
guide-testing
|
guide-testing
|
||||||
|
|
||||||
|
|
||||||
PDF_DOCS := reference
|
|
||||||
|
|
||||||
RUSTDOC_DEPS_reference := doc/full-toc.inc
|
RUSTDOC_DEPS_reference := doc/full-toc.inc
|
||||||
RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
|
RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
|
||||||
|
|
||||||
|
@ -52,13 +47,6 @@ RUSTDOC_HTML_OPTS_NO_CSS = --html-before-content=doc/version_info.html \
|
||||||
|
|
||||||
RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
|
RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
|
||||||
|
|
||||||
PANDOC_BASE_OPTS := --standalone --toc --number-sections
|
|
||||||
PANDOC_TEX_OPTS = $(PANDOC_BASE_OPTS) --from=markdown --to=latex \
|
|
||||||
--include-before-body=doc/version.tex \
|
|
||||||
--include-before-body=doc/footer.tex \
|
|
||||||
--include-in-header=doc/uptack.tex
|
|
||||||
PANDOC_EPUB_OPTS = $(PANDOC_BASE_OPTS) --to=epub
|
|
||||||
|
|
||||||
# The rustdoc executable...
|
# The rustdoc executable...
|
||||||
RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
|
RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
|
||||||
# ...with rpath included in case --disable-rpath was provided to
|
# ...with rpath included in case --disable-rpath was provided to
|
||||||
|
@ -89,30 +77,10 @@ else
|
||||||
HTML_DEPS :=
|
HTML_DEPS :=
|
||||||
endif
|
endif
|
||||||
|
|
||||||
# Check for xelatex
|
|
||||||
|
|
||||||
ifneq ($(CFG_XELATEX),)
|
|
||||||
CFG_LATEX := $(CFG_XELATEX)
|
|
||||||
XELATEX = 1
|
|
||||||
else
|
|
||||||
$(info cfg: no xelatex found, disabling LaTeX docs)
|
|
||||||
NO_PDF_DOCS = 1
|
|
||||||
endif
|
|
||||||
|
|
||||||
ifeq ($(CFG_PANDOC),)
|
|
||||||
$(info cfg: no pandoc found, omitting PDF and EPUB docs)
|
|
||||||
ONLY_HTML_DOCS = 1
|
|
||||||
endif
|
|
||||||
|
|
||||||
|
|
||||||
######################################################################
|
######################################################################
|
||||||
# Rust version
|
# Rust version
|
||||||
######################################################################
|
######################################################################
|
||||||
|
|
||||||
doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
|
|
||||||
@$(call E, version-stamp: $@)
|
|
||||||
$(Q)echo "$(CFG_VERSION)" >$@
|
|
||||||
|
|
||||||
HTML_DEPS += doc/version_info.html
|
HTML_DEPS += doc/version_info.html
|
||||||
doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
|
doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
|
||||||
$(wildcard $(D)/*.*) | doc/
|
$(wildcard $(D)/*.*) | doc/
|
||||||
|
@ -121,10 +89,10 @@ doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
|
||||||
s/SHORT_HASH/$(CFG_SHORT_VER_HASH)/; \
|
s/SHORT_HASH/$(CFG_SHORT_VER_HASH)/; \
|
||||||
s/STAMP/$(CFG_VER_HASH)/;" $< >$@
|
s/STAMP/$(CFG_VER_HASH)/;" $< >$@
|
||||||
|
|
||||||
GENERATED += doc/version.tex doc/version_info.html
|
GENERATED += doc/version_info.html
|
||||||
|
|
||||||
######################################################################
|
######################################################################
|
||||||
# Docs, from rustdoc and sometimes pandoc
|
# Docs from rustdoc
|
||||||
######################################################################
|
######################################################################
|
||||||
|
|
||||||
doc/:
|
doc/:
|
||||||
|
@ -150,20 +118,6 @@ doc/footer.inc: $(D)/footer.inc | doc/
|
||||||
$(Q)cp -PRp $< $@ 2> /dev/null
|
$(Q)cp -PRp $< $@ 2> /dev/null
|
||||||
|
|
||||||
# The (english) documentation for each doc item.
|
# The (english) documentation for each doc item.
|
||||||
|
|
||||||
define DEF_SHOULD_BUILD_PDF_DOC
|
|
||||||
SHOULD_BUILD_PDF_DOC_$(1) = 1
|
|
||||||
endef
|
|
||||||
$(foreach docname,$(PDF_DOCS),$(eval $(call DEF_SHOULD_BUILD_PDF_DOC,$(docname))))
|
|
||||||
|
|
||||||
doc/footer.tex: $(D)/footer.inc | doc/
|
|
||||||
@$(call E, pandoc: $@)
|
|
||||||
$(CFG_PANDOC) --from=html --to=latex $< --output=$@
|
|
||||||
|
|
||||||
doc/uptack.tex: $(D)/uptack.tex | doc/
|
|
||||||
$(Q)cp $< $@
|
|
||||||
|
|
||||||
# HTML (rustdoc)
|
|
||||||
DOC_TARGETS += doc/not_found.html
|
DOC_TARGETS += doc/not_found.html
|
||||||
doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
|
doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
|
||||||
@$(call E, rustdoc: $@)
|
@$(call E, rustdoc: $@)
|
||||||
|
@ -179,47 +133,6 @@ doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
|
||||||
@$$(call E, rustdoc: $$@)
|
@$$(call E, rustdoc: $$@)
|
||||||
$$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
|
$$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
|
||||||
|
|
||||||
ifneq ($(ONLY_HTML_DOCS),1)
|
|
||||||
|
|
||||||
# EPUB (pandoc directly)
|
|
||||||
DOC_TARGETS += doc/$(1).epub
|
|
||||||
doc/$(1).epub: $$(D)/$(1).md | doc/
|
|
||||||
@$$(call E, pandoc: $$@)
|
|
||||||
$$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) $$< --output=$$@
|
|
||||||
|
|
||||||
# PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
|
|
||||||
DOC_TARGETS += doc/$(1).tex
|
|
||||||
doc/$(1).tex: $$(D)/$(1).md doc/uptack.tex doc/footer.tex doc/version.tex | doc/
|
|
||||||
@$$(call E, pandoc: $$@)
|
|
||||||
$$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) $$< --output=$$@
|
|
||||||
|
|
||||||
ifneq ($(NO_PDF_DOCS),1)
|
|
||||||
ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
|
|
||||||
DOC_TARGETS += doc/$(1).pdf
|
|
||||||
ifneq ($(XELATEX),1)
|
|
||||||
doc/$(1).pdf: doc/$(1).tex
|
|
||||||
@$$(call E, latex compiler: $$@)
|
|
||||||
$$(Q)$$(CFG_LATEX) \
|
|
||||||
-interaction=batchmode \
|
|
||||||
-output-directory=doc \
|
|
||||||
$$<
|
|
||||||
else
|
|
||||||
# The version of xelatex on the snap bots seemingly ingores -output-directory
|
|
||||||
# So we'll output to . and move to the doc directory manually.
|
|
||||||
# This will leave some intermediate files in the build directory.
|
|
||||||
doc/$(1).pdf: doc/$(1).tex
|
|
||||||
@$$(call E, latex compiler: $$@)
|
|
||||||
$$(Q)$$(CFG_LATEX) \
|
|
||||||
-interaction=batchmode \
|
|
||||||
-output-directory=. \
|
|
||||||
$$<
|
|
||||||
$$(Q)mv ./$(1).pdf $$@
|
|
||||||
endif # XELATEX
|
|
||||||
endif # SHOULD_BUILD_PDF_DOCS_$(1)
|
|
||||||
endif # NO_PDF_DOCS
|
|
||||||
|
|
||||||
endif # ONLY_HTML_DOCS
|
|
||||||
|
|
||||||
endef
|
endef
|
||||||
|
|
||||||
$(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
|
$(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
|
||||||
|
|
|
@ -1,11 +1,5 @@
|
||||||
# Rust documentations
|
# Rust documentations
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
[Pandoc](http://johnmacfarlane.net/pandoc/installing.html), a universal
|
|
||||||
document converter, is required to generate docs as HTML from Rust's
|
|
||||||
source code.
|
|
||||||
|
|
||||||
## Building
|
## Building
|
||||||
|
|
||||||
To generate all the docs, just run `make docs` from the root of the repository.
|
To generate all the docs, just run `make docs` from the root of the repository.
|
||||||
|
@ -26,15 +20,12 @@ To generate an HTML version of a doc from Markdown manually, you can do
|
||||||
something like:
|
something like:
|
||||||
|
|
||||||
~~~~
|
~~~~
|
||||||
pandoc --from=markdown --to=html5 --number-sections -o reference.html reference.md
|
rustdoc reference.md
|
||||||
~~~~
|
~~~~
|
||||||
|
|
||||||
(`reference.md` being the Rust Reference Manual.)
|
(`reference.md` being the Rust Reference Manual.)
|
||||||
|
|
||||||
The syntax for pandoc flavored markdown can be found at:
|
An overview of how to use the `rustdoc` command is available [in the docs][1].
|
||||||
|
Further details are available from the command line by with `rustdoc --help`.
|
||||||
|
|
||||||
- http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
|
[1]: https://github.com/rust-lang/rust/blob/master/src/doc/trpl/documentation.md
|
||||||
|
|
||||||
A nice quick reference (for non-pandoc markdown) is at:
|
|
||||||
|
|
||||||
- http://kramdown.gettalong.org/quickref.html
|
|
||||||
|
|
Loading…
Reference in New Issue