mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
bea8b81225
rust/mk/docs.mk

278 lines
8.2 KiB
Makefile
Raw Normal View History

doc: tidy and cleanup CSS deps, add tutorial PDF generation
2013-10-11 13:21:46 -05:00
# Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
Reliciense makefiles and testsuite. Yup.
2012-12-10 19:32:48 -06:00
# file at the top-level directory of this distribution and at
# http://rust-lang.org/COPYRIGHT.
#
# Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
# http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
# <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
# option. This file may not be copied, modified, or distributed
# except according to those terms.
Start splitting up Makefile.in
2011-05-01 15:18:52 -05:00
######################################################################
"The Rust Programming Language" This pulls all of our long-form documentation into a single document, nicknamed "the book" and formally titled "The Rust Programming Language." A few things motivated this change: * People knew of The Guide, but not the individual Guides. This merges them together, helping discoverability. * You can get all of Rust's longform documentation in one place, which is nice. * We now have rustbook in-tree, which can generate this kind of documentation. While its style is basic, the general idea is much better: a table of contents on the left-hand side. * Rather than a almost 10,000-line guide.md, there are now smaller files per section.
2014-12-02 08:20:48 -06:00
# The various pieces of standalone documentation.
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
#
# The DOCS variable is their names (with no file extension).
#
mk: only build PDFs of the manual and tutorial. This restores the old behaviour (as compared to building PDF versions of all standalone docs), because some of the guides use unicode characters, which seems to make pdftex unhappy.
2014-03-08 22:54:16 -06:00
# PDF_DOCS lists the targets for which PDF documentation should be
# build.
#
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
# RUSTDOC_FLAGS_xyz variables are extra arguments to pass to the
# rustdoc invocation for xyz.
#
# RUSTDOC_DEPS_xyz are extra dependencies for the rustdoc invocation
# on xyz.
#
# L10N_LANGS are the languages for which the docs have been
# translated.
Start splitting up Makefile.in
2011-05-01 15:18:52 -05:00
######################################################################
"The Rust Programming Language" This pulls all of our long-form documentation into a single document, nicknamed "the book" and formally titled "The Rust Programming Language." A few things motivated this change: * People knew of The Guide, but not the individual Guides. This merges them together, helping discoverability. * You can get all of Rust's longform documentation in one place, which is nice. * We now have rustbook in-tree, which can generate this kind of documentation. While its style is basic, the general idea is much better: a table of contents on the left-hand side. * Rather than a almost 10,000-line guide.md, there are now smaller files per section.
2014-12-02 08:20:48 -06:00
DOCS := index intro tutorial complement-bugreport \
complement-lang-faq complement-design-faq complement-project-faq \
rustdoc reference
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
Add stub deprecation files for each of the old guides. There are hundreds of stackoverflow answers, reddit posts and blog articles that link to these documents, so it's a nicer user experience if they're not plain 404s. The intention is to let these hang around only for relatively short while. The alpha is likely to bring in many new users and they will be reading the documents mentioned above.
2015-01-09 02:47:09 -06:00
# Legacy guides, preserved for a while to reduce the number of 404s
DOCS += guide-crates guide-error-handling guide-ffi guide-macros guide \
guide-ownership guide-plugins guide-pointers guide-strings guide-tasks \
guide-testing
"The Rust Programming Language" This pulls all of our long-form documentation into a single document, nicknamed "the book" and formally titled "The Rust Programming Language." A few things motivated this change: * People knew of The Guide, but not the individual Guides. This merges them together, helping discoverability. * You can get all of Rust's longform documentation in one place, which is nice. * We now have rustbook in-tree, which can generate this kind of documentation. While its style is basic, the general idea is much better: a table of contents on the left-hand side. * Rather than a almost 10,000-line guide.md, there are now smaller files per section.
2014-12-02 08:20:48 -06:00
PDF_DOCS := reference
mk: only build PDFs of the manual and tutorial. This restores the old behaviour (as compared to building PDF versions of all standalone docs), because some of the guides use unicode characters, which seems to make pdftex unhappy.
2014-03-08 22:54:16 -06:00
Guide: Puts the toc again in the doc Closes #17505
2014-11-06 17:01:45 -06:00
RUSTDOC_DEPS_reference := doc/full-toc.inc
RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
L10N_LANGS := ja
# Generally no need to edit below here.
Start splitting up Makefile.in
2011-05-01 15:18:52 -05:00
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
# The options are passed to the documentation generators.
Allow external html in rustdoc for crates. Updated documentation to reflect md->html. Modularized external file loading.
2014-06-28 05:35:25 -05:00
RUSTDOC_HTML_OPTS_NO_CSS = --html-before-content=doc/version_info.html \
--html-in-header=doc/favicon.inc \
--html-after-content=doc/footer.inc \
rustdoc: Submit examples to play.rust-lang.org This grows a new option inside of rustdoc to add the ability to submit examples to an external website. If the `--markdown-playground-url` command line option or crate doc attribute `html_playground_url` is present, then examples will have a button on hover to submit the code to the playground specified. This commit enables submission of example code to play.rust-lang.org. The code submitted is that which is tested by rustdoc, not necessarily the exact code shown in the example. Closes #14654
2014-06-06 11:12:18 -05:00
--markdown-playground-url='http://play.rust-lang.org/'
Start splitting up Makefile.in
2011-05-01 15:18:52 -05:00
Render not_found with an absolute path to the rust stylesheet
2014-05-14 12:45:51 -05:00
RUSTDOC_HTML_OPTS = $(RUSTDOC_HTML_OPTS_NO_CSS) --markdown-css rust.css
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
PANDOC_BASE_OPTS := --standalone --toc --number-sections
Changed LaTex $\bot$s to ⊥ In the HTML version of the documentation, it isn't rendered so might as well use the unicode representation. Part of the problem was that putting a math unicode character wasn't rendering properly in the pdf, so extra steps were needed to define the unicode charecter ⊥ in reference.tex closes #15285
2014-12-18 17:27:50 -06:00
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
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
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
# ./configure
RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
Begin shift over to using pandoc, markdown and llnextgen for reference manual. Fix man page URL while at it.
2012-01-12 21:10:30 -06:00
"The Rust Programming Language" This pulls all of our long-form documentation into a single document, nicknamed "the book" and formally titled "The Rust Programming Language." A few things motivated this change: * People knew of The Guide, but not the individual Guides. This merges them together, helping discoverability. * You can get all of Rust's longform documentation in one place, which is nice. * We now have rustbook in-tree, which can generate this kind of documentation. While its style is basic, the general idea is much better: a table of contents on the left-hand side. * Rather than a almost 10,000-line guide.md, there are now smaller files per section.
2014-12-02 08:20:48 -06:00
# The rustbook executable...
RUSTBOOK_EXE = $(HBIN2_H_$(CFG_BUILD))/rustbook$(X_$(CFG_BUILD))
# ...with rpath included in case --disable-rpath was provided to
# ./configure
RUSTBOOK = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTBOOK_EXE)
Rewrite the doc makefile for doc => src/doc This continues to generate all documentation into doc, but it now looks for source files in src/doc Closes #11860 Closes #11970
2014-01-28 16:15:29 -06:00
D := $(S)src/doc
"The Rust Programming Language" This pulls all of our long-form documentation into a single document, nicknamed "the book" and formally titled "The Rust Programming Language." A few things motivated this change: * People knew of The Guide, but not the individual Guides. This merges them together, helping discoverability. * You can get all of Rust's longform documentation in one place, which is nice. * We now have rustbook in-tree, which can generate this kind of documentation. While its style is basic, the general idea is much better: a table of contents on the left-hand side. * Rather than a almost 10,000-line guide.md, there are now smaller files per section.
2014-12-02 08:20:48 -06:00
DOC_TARGETS := trpl
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
COMPILER_DOC_TARGETS :=
DOC_L10N_TARGETS :=
# If NO_REBUILD is set then break the dependencies on rustdoc so we
# build the documentation without having to rebuild rustdoc.
ifeq ($(NO_REBUILD),)
HTML_DEPS := $(RUSTDOC_EXE)
else
HTML_DEPS :=
endif
Only accept xelatex for building PDF docs None of the others work, so let's remove them. Fixes #17220.
2015-02-05 21:14:12 -06:00
# Check for xelatex
docs: disable PDF docs when latex _isn't_ present
2015-02-11 00:16:37 -06:00
ifneq ($(CFG_XELATEX),)
doc: have a real switch b/w LaTeX compilers
2014-03-09 05:21:05 -05:00
CFG_LATEX := $(CFG_XELATEX)
Prefer lualatex, xelatex, pdflatex, in that order. #12804
2014-09-09 17:47:47 -05:00
XELATEX = 1
Only accept xelatex for building PDF docs None of the others work, so let's remove them. Fixes #17220.
2015-02-05 21:14:12 -06:00
else
$(info cfg: no xelatex found, disabling LaTeX docs)
NO_PDF_DOCS = 1
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
endif
ifeq ($(CFG_PANDOC),)
$(info cfg: no pandoc found, omitting PDF and EPUB docs)
ONLY_HTML_DOCS = 1
endif
rust_version.html is a HTML_DEPS and every html has it as dependecy
2014-01-06 15:38:20 -06:00
######################################################################
# Rust version
######################################################################
doc: fix version stamp for TeX files This fixes a regression introduced in 3d57b240ab1fd038b3a41fe2042dc9a0544ea53e.
2014-01-17 12:38:48 -06:00
doc: auto-generate LaTeX includes
2014-03-09 06:41:27 -05:00
doc/version.tex: $(MKFILE_DEPS) $(wildcard $(D)/*.*) | doc/
rust_version.html is a HTML_DEPS and every html has it as dependecy
2014-01-06 15:38:20 -06:00
@$(call E, version-stamp: $@)
$(Q)echo "$(CFG_VERSION)" >$@
HTML_DEPS += doc/version_info.html
Rewrite the doc makefile for doc => src/doc This continues to generate all documentation into doc, but it now looks for source files in src/doc Closes #11860 Closes #11970
2014-01-28 16:15:29 -06:00
doc/version_info.html: $(D)/version_info.html.template $(MKFILE_DEPS) \
$(wildcard $(D)/*.*) | doc/
rust_version.html is a HTML_DEPS and every html has it as dependecy
2014-01-06 15:38:20 -06:00
@$(call E, version-info: $@)
docs: Fix short hash link to github The escaped newline in the middle of the variable reference breaks the short hash substitution, leaving the link text exmpty; rewrap so that each replacement is on its own line.
2014-10-04 13:41:37 -05:00
$(Q)sed -e "s/VERSION/$(CFG_RELEASE)/; \
s/SHORT_HASH/$(CFG_SHORT_VER_HASH)/; \
rust_version.html is a HTML_DEPS and every html has it as dependecy
2014-01-06 15:38:20 -06:00
s/STAMP/$(CFG_VER_HASH)/;" $< >$@
doc: auto-generate LaTeX includes
2014-03-09 06:41:27 -05:00
GENERATED += doc/version.tex doc/version_info.html
rust_version.html is a HTML_DEPS and every html has it as dependecy
2014-01-06 15:38:20 -06:00
Refactor the doc building rules a bit, sensitize them to the presence or absence of xetex and luatex (for now).
2012-01-18 16:14:28 -06:00
######################################################################
doc: remove node.js dependency `prep.js` outputs its own HTML directives, which `pandoc` cannot recognize when converting the document into LaTeX (this is why the PDF docs have never been highlighted as of now). Note that if we were to add the `.rust` class to snippets, we could probably use pandoc's native highlighting capatibilities i.e. Kate.
2014-03-09 05:06:03 -05:00
# Docs, from rustdoc and sometimes pandoc
Refactor the doc building rules a bit, sensitize them to the presence or absence of xetex and luatex (for now).
2012-01-18 16:14:28 -06:00
######################################################################
doc: Run language ref through prep.js This is so we can strip out support code needed to make the examples work, and as a bonus it does syntax highlighting.
2012-03-20 19:50:32 -05:00
Rewrite the doc makefile for doc => src/doc This continues to generate all documentation into doc, but it now looks for source files in src/doc Closes #11860 Closes #11970
2014-01-28 16:15:29 -06:00
doc/:
@mkdir -p $@
First phase of migrating the wiki to the internal docs #11078
2013-12-22 20:21:45 -06:00
HTML_DEPS += doc/rust.css
Rewrite the doc makefile for doc => src/doc This continues to generate all documentation into doc, but it now looks for source files in src/doc Closes #11860 Closes #11970
2014-01-28 16:15:29 -06:00
doc/rust.css: $(D)/rust.css | doc/
Tidy up doc make rules.
2012-03-26 19:59:09 -05:00
@$(call E, cp: $@)
$(Q)cp -a $< $@ 2> /dev/null
doc: add license information for gen. files
2014-02-07 13:46:39 -06:00
HTML_DEPS += doc/favicon.inc
doc/favicon.inc: $(D)/favicon.inc | doc/
@$(call E, cp: $@)
$(Q)cp -a $< $@ 2> /dev/null
Rewrite the doc makefile for doc => src/doc This continues to generate all documentation into doc, but it now looks for source files in src/doc Closes #11860 Closes #11970
2014-01-28 16:15:29 -06:00
doc/full-toc.inc: $(D)/full-toc.inc | doc/
Display the full TOC in the manual. Closes #4194
2012-12-14 20:06:11 -06:00
@$(call E, cp: $@)
$(Q)cp -a $< $@ 2> /dev/null
doc: add license information for gen. files
2014-02-07 13:46:39 -06:00
HTML_DEPS += doc/footer.inc
doc/footer.inc: $(D)/footer.inc | doc/
@$(call E, cp: $@)
$(Q)cp -a $< $@ 2> /dev/null
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
# The (english) documentation for each doc item.
mk: reorganize doc build to fix dependencies. #6042 Most of our documentation requires both pandoc and node.js. This simplifies the logic around those checks and fixes an error when building without node.js but with pandoc.
2013-04-24 00:51:48 -05:00
mk: only build PDFs of the manual and tutorial. This restores the old behaviour (as compared to building PDF versions of all standalone docs), because some of the guides use unicode characters, which seems to make pdftex unhappy.
2014-03-08 22:54:16 -06:00
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))))
mk: Fix warnings about duplicated rules The footer.tex rule didn't depend on $(1) of the macro it was being defined in, so it was getting duplicated, causing many warnings.
2014-03-12 12:35:17 -05:00
doc/footer.tex: $(D)/footer.inc | doc/
Test fixes from rolling up PRs Closes #12803 (std: Relax an assertion in oneshot selection) r=brson Closes #12818 (green: Fix a scheduler assertion on yielding) r=brson Closes #12819 (doc: discuss try! in std::io) r=alexcrichton Closes #12820 (Use generic impls for `Hash`) r=alexcrichton Closes #12826 (Remove remaining nolink usages) r=alexcrichton Closes #12835 (Emacs: always jump the cursor if needed on indent) r=brson Closes #12838 (Json method cleanup) r=alexcrichton Closes #12843 (rustdoc: whitelist the headers that get a § on hover) r=alexcrichton Closes #12844 (docs: add two unlisted libraries to the index page) r=pnkfelix Closes #12846 (Added a test that checks that unary structs can be mutably borrowed) r=sfackler Closes #12847 (mk: Fix warnings about duplicated rules) r=nmatsakis
2014-03-12 12:31:52 -05:00
@$(call E, pandoc: $@)
$(CFG_PANDOC) --from=html --to=latex $< --output=$@
mk: Fix warnings about duplicated rules The footer.tex rule didn't depend on $(1) of the macro it was being defined in, so it was getting duplicated, causing many warnings.
2014-03-12 12:35:17 -05:00
Changed LaTex $\bot$s to ⊥ In the HTML version of the documentation, it isn't rendered so might as well use the unicode representation. Part of the problem was that putting a math unicode character wasn't rendering properly in the pdf, so extra steps were needed to define the unicode charecter ⊥ in reference.tex closes #15285
2014-12-18 17:27:50 -06:00
doc/uptack.tex: $(D)/uptack.tex | doc/
$(Q)cp $< $@
Render not_found with an absolute path to the rust stylesheet
2014-05-14 12:45:51 -05:00
# HTML (rustdoc)
DOC_TARGETS += doc/not_found.html
doc/not_found.html: $(D)/not_found.md $(HTML_DEPS) | doc/
mk: Less noisy rustdoc invocations
2014-06-01 13:09:30 -05:00
@$(call E, rustdoc: $@)
$(Q)$(RUSTDOC) $(RUSTDOC_HTML_OPTS_NO_CSS) \
--markdown-css http://doc.rust-lang.org/rust.css $<
Render not_found with an absolute path to the rust stylesheet
2014-05-14 12:45:51 -05:00
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
define DEF_DOC
# HTML (rustdoc)
DOC_TARGETS += doc/$(1).html
doc/$(1).html: $$(D)/$(1).md $$(HTML_DEPS) $$(RUSTDOC_DEPS_$(1)) | doc/
@$$(call E, rustdoc: $$@)
mk: Less noisy rustdoc invocations
2014-06-01 13:09:30 -05:00
$$(Q)$$(RUSTDOC) $$(RUSTDOC_HTML_OPTS) $$(RUSTDOC_FLAGS_$(1)) $$<
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
ifneq ($(ONLY_HTML_DOCS),1)
# EPUB (pandoc directly)
DOC_TARGETS += doc/$(1).epub
doc/$(1).epub: $$(D)/$(1).md | doc/
@$$(call E, pandoc: $$@)
doc: remove node.js dependency `prep.js` outputs its own HTML directives, which `pandoc` cannot recognize when converting the document into LaTeX (this is why the PDF docs have never been highlighted as of now). Note that if we were to add the `.rust` class to snippets, we could probably use pandoc's native highlighting capatibilities i.e. Kate.
2014-03-09 05:06:03 -05:00
$$(CFG_PANDOC) $$(PANDOC_EPUB_OPTS) $$< --output=$$@
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
# PDF (md =(pandoc)=> tex =(pdflatex)=> pdf)
DOC_TARGETS += doc/$(1).tex
Changed LaTex $\bot$s to ⊥ In the HTML version of the documentation, it isn't rendered so might as well use the unicode representation. Part of the problem was that putting a math unicode character wasn't rendering properly in the pdf, so extra steps were needed to define the unicode charecter ⊥ in reference.tex closes #15285
2014-12-18 17:27:50 -06:00
doc/$(1).tex: $$(D)/$(1).md doc/uptack.tex doc/footer.tex doc/version.tex | doc/
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
@$$(call E, pandoc: $$@)
doc: remove node.js dependency `prep.js` outputs its own HTML directives, which `pandoc` cannot recognize when converting the document into LaTeX (this is why the PDF docs have never been highlighted as of now). Note that if we were to add the `.rust` class to snippets, we could probably use pandoc's native highlighting capatibilities i.e. Kate.
2014-03-09 05:06:03 -05:00
$$(CFG_PANDOC) $$(PANDOC_TEX_OPTS) $$< --output=$$@
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
ifneq ($(NO_PDF_DOCS),1)
mk: only build PDFs of the manual and tutorial. This restores the old behaviour (as compared to building PDF versions of all standalone docs), because some of the guides use unicode characters, which seems to make pdftex unhappy.
2014-03-08 22:54:16 -06:00
ifeq ($$(SHOULD_BUILD_PDF_DOC_$(1)),1)
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
DOC_TARGETS += doc/$(1).pdf
Prefer lualatex, xelatex, pdflatex, in that order. #12804
2014-09-09 17:47:47 -05:00
ifneq ($(XELATEX),1)
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
doc/$(1).pdf: doc/$(1).tex
doc: have a real switch b/w LaTeX compilers
2014-03-09 05:21:05 -05:00
@$$(call E, latex compiler: $$@)
$$(Q)$$(CFG_LATEX) \
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
-interaction=batchmode \
-output-directory=doc \
$$<
Prefer lualatex, xelatex, pdflatex, in that order. #12804
2014-09-09 17:47:47 -05:00
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
mk: only build PDFs of the manual and tutorial. This restores the old behaviour (as compared to building PDF versions of all standalone docs), because some of the guides use unicode characters, which seems to make pdftex unhappy.
2014-03-08 22:54:16 -06:00
endif # SHOULD_BUILD_PDF_DOCS_$(1)
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
endif # NO_PDF_DOCS
endif # ONLY_HTML_DOCS
endef
$(foreach docname,$(DOCS),$(eval $(call DEF_DOC,$(docname))))
mk: reorganize doc build to fix dependencies. #6042 Most of our documentation requires both pandoc and node.js. This simplifies the logic around those checks and fixes an error when building without node.js but with pandoc.
2013-04-24 00:51:48 -05:00
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
Refactor the doc building rules a bit, sensitize them to the presence or absence of xetex and luatex (for now).
2012-01-18 16:14:28 -06:00
######################################################################
libstd: Rename libcore to libstd and libstd to libextra; update makefiles. This only changes the directory names; it does not change the "real" metadata names.
2013-05-17 12:45:09 -05:00
# Rustdoc (libstd/extra)
Refactor the doc building rules a bit, sensitize them to the presence or absence of xetex and luatex (for now).
2012-01-18 16:14:28 -06:00
######################################################################
Start splitting up Makefile.in
2011-05-01 15:18:52 -05:00
Establish 'core' library separate from 'std'.
2011-12-05 18:46:37 -06:00
build: Switch from naturaldocs to rustdoc
2012-03-10 00:53:46 -06:00
# The library documenting macro
Refactor the build system for easily adding crates Before this patch, if you wanted to add a crate to the build system you had to change about 100 lines across 8 separate makefiles. This is highly error prone and opaque to all but a few. This refactoring is targeted at consolidating this effort so adding a new crate adds one line in one file in a way that everyone can understand it.
2014-01-24 21:27:22 -06:00
#
rustdoc: Out with the old, in with the new Removes old rustdoc, moves rustdoc_ng into its place instead (plus drops the _ng suffix). Also shreds all reference to rustdoc_ng from the Makefile rules.
2013-09-22 01:25:48 -05:00
# $(1) - The crate name (std/extra)
rustdoc: pass through --cfg to rustc Closes #10623
2013-11-24 22:31:21 -06:00
#
# Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
define DEF_LIB_DOC
# If NO_REBUILD is set then break the dependencies on rustdoc so we
# build crate documentation without having to rebuild rustdoc.
ifeq ($(NO_REBUILD),)
LIB_DOC_DEP_$(1) = \
$$(CRATEFILE_$(1)) \
$$(RSINPUTS_$(1)) \
$$(RUSTDOC_EXE) \
$$(foreach dep,$$(RUST_DEPS_$(1)), \
mk: Stop generating docs for deprecated crates These crates are all deprecated for their rust-lang/$crate equivalents and by generating docs we're generating broken links. The documentation for these crates are generated out-of-tree and are managed separately, so we're not losing the documentation altogether, just the links from the main distribution's docs. Closes #20096
2014-12-21 01:29:59 -06:00
$$(TLIB2_T_$(CFG_BUILD)_H_$(CFG_BUILD))/stamp.$$(dep)) \
$$(foreach dep,$$(filter $$(DOC_CRATES), $$(RUST_DEPS_$(1))), \
mk: Ensure docs have relative links to each other When generating documentation, rustdoc has the ability to generate relative links within the current distribution of crates to one another. To do this, it must recognize when a crate's documentation is in the same output directory. The current threshold for "local documentation for crate X being available" is whether the directory "doc/X" exists. This change modifies the build system to have new dependencies for each directory of upstream crates for a rustdoc invocation. This will ensure that when building documentation that all the crates in the standard distribution are guaranteed to have relative links to one another. This change is prompted by guaranteeing that offline docs always work with one another. Before this change, races could mean that some docs were built before others, and hence may have http links when relative links would suffice. Closes #14747
2014-06-09 15:00:18 -05:00
doc/$$(dep)/)
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
else
LIB_DOC_DEP_$(1) = $$(CRATEFILE_$(1)) $$(RSINPUTS_$(1))
endif
Don't include rpath lines in dependency lists The rpath variable should only be used when executing commands, if it leaks into a dependency list is causes havoc with the dependencies.
2014-02-06 17:43:27 -06:00
mk: Ensure docs have relative links to each other When generating documentation, rustdoc has the ability to generate relative links within the current distribution of crates to one another. To do this, it must recognize when a crate's documentation is in the same output directory. The current threshold for "local documentation for crate X being available" is whether the directory "doc/X" exists. This change modifies the build system to have new dependencies for each directory of upstream crates for a rustdoc invocation. This will ensure that when building documentation that all the crates in the standard distribution are guaranteed to have relative links to one another. This change is prompted by guaranteeing that offline docs always work with one another. Before this change, races could mean that some docs were built before others, and hence may have http links when relative links would suffice. Closes #14747
2014-06-09 15:00:18 -05:00
doc/$(1)/:
$$(Q)mkdir -p $$@
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
$(2) += doc/$(1)/index.html
mk: Add a dummy CFG_COMPILER_HOST_TRIPLE to rustdoc invocation. Otherwise it will prohibit `make compiler-docs` on Windows.
2014-04-08 12:45:53 -05:00
doc/$(1)/index.html: CFG_COMPILER_HOST_TRIPLE = $(CFG_TARGET)
mk: Ensure docs have relative links to each other When generating documentation, rustdoc has the ability to generate relative links within the current distribution of crates to one another. To do this, it must recognize when a crate's documentation is in the same output directory. The current threshold for "local documentation for crate X being available" is whether the directory "doc/X" exists. This change modifies the build system to have new dependencies for each directory of upstream crates for a rustdoc invocation. This will ensure that when building documentation that all the crates in the standard distribution are guaranteed to have relative links to one another. This change is prompted by guaranteeing that offline docs always work with one another. Before this change, races could mean that some docs were built before others, and hence may have http links when relative links would suffice. Closes #14747
2014-06-09 15:00:18 -05:00
doc/$(1)/index.html: $$(LIB_DOC_DEP_$(1)) doc/$(1)/
mk: Add missing colon
2014-08-01 18:48:41 -05:00
@$$(call E, rustdoc: $$@)
Don't use the same llvmdeps.rs for every host.
2014-11-25 17:28:49 -06:00
$$(Q)CFG_LLVM_LINKAGE_FILE=$$(LLVM_LINKAGE_PATH_$(CFG_BUILD)) \
$$(RUSTDOC) --cfg dox --cfg stage2 $$<
Add a compiler-docs target
2013-12-28 23:13:19 -06:00
endef
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
$(foreach crate,$(DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),DOC_TARGETS)))
$(foreach crate,$(COMPILER_DOC_CRATES),$(eval $(call DEF_LIB_DOC,$(crate),COMPILER_DOC_TARGETS)))
Refactor the doc building rules a bit, sensitize them to the presence or absence of xetex and luatex (for now).
2012-01-18 16:14:28 -06:00
ifdef CFG_DISABLE_DOCS
$(info cfg: disabling doc build (CFG_DISABLE_DOCS))
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
DOC_TARGETS :=
mk: Don't build any docs with --disable-docs.
2014-05-27 19:17:17 -05:00
COMPILER_DOC_TARGETS :=
Refactor the doc building rules a bit, sensitize them to the presence or absence of xetex and luatex (for now).
2012-01-18 16:14:28 -06:00
endif
mk: rewrite the documentation handling. This converts it to be very similar to crates.mk, with a single list of the documentation items creating all the necessary bits and pieces. Changes include: - rustdoc is used to render HTML & test standalone docs - documentation building now obeys NO_REBUILD=1 - testing standalone docs now obeys NO_REBUILD=1 - L10N is slightly less broken (in particular, it shares dependencies and code with the rest of the code) - PDFs can be built for all documentation items, not just tutorial and manual - removes the obsolete & unused extract-tests.py script - adjust the CSS for standalone docs to use the rustdoc syntax highlighting
2014-03-08 08:41:31 -06:00
docs: $(DOC_TARGETS)
compiler-docs: $(COMPILER_DOC_TARGETS)
"The Rust Programming Language" This pulls all of our long-form documentation into a single document, nicknamed "the book" and formally titled "The Rust Programming Language." A few things motivated this change: * People knew of The Guide, but not the individual Guides. This merges them together, helping discoverability. * You can get all of Rust's longform documentation in one place, which is nice. * We now have rustbook in-tree, which can generate this kind of documentation. While its style is basic, the general idea is much better: a table of contents on the left-hand side. * Rather than a almost 10,000-line guide.md, there are now smaller files per section.
2014-12-02 08:20:48 -06:00
Fix dead links in the guide and reorganize
2015-01-08 12:27:03 -06:00
trpl: doc/book/index.html
"The Rust Programming Language" This pulls all of our long-form documentation into a single document, nicknamed "the book" and formally titled "The Rust Programming Language." A few things motivated this change: * People knew of The Guide, but not the individual Guides. This merges them together, helping discoverability. * You can get all of Rust's longform documentation in one place, which is nice. * We now have rustbook in-tree, which can generate this kind of documentation. While its style is basic, the general idea is much better: a table of contents on the left-hand side. * Rather than a almost 10,000-line guide.md, there are now smaller files per section.
2014-12-02 08:20:48 -06:00
Ensure that the book is built after the doc/ directory. Without this, rustbook was failing because it was expecting the directory to exist. (Previously, rustbook was just silently failing to install the CSS files due to this.)
2015-01-09 03:26:31 -06:00
doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md) | doc/
"The Rust Programming Language" This pulls all of our long-form documentation into a single document, nicknamed "the book" and formally titled "The Rust Programming Language." A few things motivated this change: * People knew of The Guide, but not the individual Guides. This merges them together, helping discoverability. * You can get all of Rust's longform documentation in one place, which is nice. * We now have rustbook in-tree, which can generate this kind of documentation. While its style is basic, the general idea is much better: a table of contents on the left-hand side. * Rather than a almost 10,000-line guide.md, there are now smaller files per section.
2014-12-02 08:20:48 -06:00
$(Q)rm -rf doc/book
$(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book
Reference in New Issue Copy Permalink