diff options
| -rw-r--r-- | mk/docs.mk | 91 | ||||
| -rw-r--r-- | src/doc/README.md | 17 |
2 files changed, 6 insertions, 102 deletions
diff --git a/mk/docs.mk b/mk/docs.mk index c547e35bb70..b06ff4a6027 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -13,9 +13,6 @@ # # 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 invocation for xyz. # @@ -35,8 +32,6 @@ DOCS += guide-crates guide-error-handling guide-ffi guide-macros guide \ guide-testing -PDF_DOCS := reference - RUSTDOC_DEPS_reference := 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 -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... RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD)) # ...with rpath included in case --disable-rpath was provided to @@ -89,30 +77,10 @@ else HTML_DEPS := 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 ###################################################################### -doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/ - @$(call E, version-stamp: $@) - $(Q)echo "$(CFG_VERSION)" >$@ - HTML_DEPS += doc/version_info.html doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \ $(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/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/: @@ -150,20 +118,6 @@ doc/footer.inc: $(D)/footer.inc | doc/ $(Q)cp -PRp $< $@ 2> /dev/null # 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/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/ @$(call E, rustdoc: $@) @@ -179,47 +133,6 @@ doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/ @$$(call E, rustdoc: $$@) $$(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 $(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname)))) diff --git a/src/doc/README.md b/src/doc/README.md index 3b12ffe8f11..c09f28ae4f6 100644 --- a/src/doc/README.md +++ b/src/doc/README.md @@ -1,11 +1,5 @@ # 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 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: ~~~~ -pandoc --from=markdown --to=html5 --number-sections -o reference.html reference.md +rustdoc reference.md ~~~~ (`reference.md` being the Rust Reference Manual.) -The syntax for pandoc flavored markdown can be found at: - -- http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown - -A nice quick reference (for non-pandoc markdown) is 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://kramdown.gettalong.org/quickref.html +[1]: https://github.com/rust-lang/rust/blob/master/src/doc/trpl/documentation.md |