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

223 lines
7.0 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).
#
# 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
######################################################################
mk: Move some old docs to the deprecated list
2015-11-03 14:46:06 -06:00
DOCS := index \
"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
complement-lang-faq complement-design-faq complement-project-faq \
Generate grammar.html and link to it from the reference. Fixes #19278
2015-02-13 17:00:00 -06:00
rustdoc reference grammar
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 \
mk: Move some old docs to the deprecated list
2015-11-03 14:46:06 -06:00
guide-testing tutorial intro
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
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 \
Use https URLs to refer to rust-lang.org where appropriate. Also fixes a few outdated links.
2015-08-09 16:15:05 -05:00
--markdown-playground-url='https://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
# 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)
Rename `error-index-generator` to `error_index_generator` This is because the tool compiler passes the name of the tool as a command line `--cfg`. The improved session config parser is stricter and no longer permits invalid meta items (such as "error-index-generator").
2016-02-15 00:26:37 -06:00
# The error_index_generator executable...
ERR_IDX_GEN_EXE = $(HBIN2_H_$(CFG_BUILD))/error_index_generator$(X_$(CFG_BUILD))
Add error index generator.
2015-05-02 19:57:41 -05:00
ERR_IDX_GEN = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(ERR_IDX_GEN_EXE)
Update Makefile
2016-02-07 06:03:11 -06:00
ERR_IDX_GEN_MD = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(ERR_IDX_GEN_EXE) markdown
Add error index generator.
2015-05-02 19:57:41 -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
D := $(S)src/doc
Also remove build steps for style
2016-08-25 14:20:31 -05:00
DOC_TARGETS := book nomicon error-index
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.
Revert "mk: fix some undefined variable warnings" This reverts commit d03712977d7c913044f2b863269c4491d7fa7c36.
2016-02-02 01:27:04 -06:00
ifeq ($(NO_REBUILD),)
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
HTML_DEPS := $(RUSTDOC_EXE)
else
HTML_DEPS :=
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
rust_version.html is a HTML_DEPS and every html has it as dependecy
2014-01-06 15:38:20 -06:00
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)/;" $< >$@
mk/docs: remove Pandoc and LaTeX elements.
2015-08-11 19:12:11 -05:00
GENERATED += 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
######################################################################
mk/docs: remove Pandoc and LaTeX elements.
2015-08-11 19:12:11 -05:00
# Docs from rustdoc
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: $@)
docs.mk: use posix arguments for cp `cp -a` is a GNU extension. Use an alternate combinaison of POSIX options (`-PRp`) that do nearly the same. The difference is `-a` will preserve context, links and xattr attributes, whereas `-p` not. But as we use it only for copy a file, there is no difference in the current context.
2015-02-14 07:01:16 -06:00
$(Q)cp -PRp $< $@ 2> /dev/null
Tidy up doc make rules.
2012-03-26 19:59:09 -05:00
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: $@)
docs.mk: use posix arguments for cp `cp -a` is a GNU extension. Use an alternate combinaison of POSIX options (`-PRp`) that do nearly the same. The difference is `-a` will preserve context, links and xattr attributes, whereas `-p` not. But as we use it only for copy a file, there is no difference in the current context.
2015-02-14 07:01:16 -06:00
$(Q)cp -PRp $< $@ 2> /dev/null
doc: add license information for gen. files
2014-02-07 13:46:39 -06: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/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: $@)
docs.mk: use posix arguments for cp `cp -a` is a GNU extension. Use an alternate combinaison of POSIX options (`-PRp`) that do nearly the same. The difference is `-a` will preserve context, links and xattr attributes, whereas `-p` not. But as we use it only for copy a file, there is no difference in the current context.
2015-02-14 07:01:16 -06:00
$(Q)cp -PRp $< $@ 2> /dev/null
Display the full TOC in the manual. Closes #4194
2012-12-14 20:06:11 -06:00
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: $@)
docs.mk: use posix arguments for cp `cp -a` is a GNU extension. Use an alternate combinaison of POSIX options (`-PRp`) that do nearly the same. The difference is `-a` will preserve context, links and xattr attributes, whereas `-p` not. But as we use it only for copy a file, there is no difference in the current context.
2015-02-14 07:01:16 -06:00
$(Q)cp -PRp $< $@ 2> /dev/null
doc: add license information for gen. files
2014-02-07 13:46:39 -06: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 (english) documentation for each doc item.
Render not_found with an absolute path to the rust stylesheet
2014-05-14 12:45:51 -05:00
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) \
Remove numbers all together from not_found.html
2015-06-09 14:47:48 -05:00
--markdown-no-toc \
Use https URLs to refer to rust-lang.org where appropriate. Also fixes a few outdated links.
2015-08-09 16:15:05 -05:00
--markdown-css https://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
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.
Revert "mk: fix some undefined variable warnings" This reverts commit d03712977d7c913044f2b863269c4491d7fa7c36.
2016-02-02 01:27:04 -06:00
ifeq ($(NO_REBUILD),)
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
LIB_DOC_DEP_$(1) = \
$$(CRATEFILE_$(1)) \
$$(RSINPUTS_$(1)) \
$$(RUSTDOC_EXE) \
mk: Move disable-jemalloc logic into makefiles The `--disable-jemalloc` configure option has a failure mode where it will create a distribution that is not compatible with other compilers. For example the nightly for Linux will assume that it will link to jemalloc by default as an allocator for executable crates. If, however, a standard library is used which was built via `./configure --disable-jemalloc` then this will fail because the jemalloc crate wasn't built. While this seems somewhat reasonable as a niche situation, the same mechanism is used for disabling jemalloc for platforms that just don't support it. For example if the rumprun target is compiled then the sibiling Linux target *also* doesn't have jemalloc. This is currently a problem for our cross-build nightlies which build many targets. If rumprun is also built, it will disable jemalloc for all targets, which isn't desired. This commit moves the platform-specific disabling of jemalloc as hardcoded logic into the makefiles that is scoped per-platform. This way when configuring multiple targets **without the `--disable-jemalloc` option specified** all targets will get jemalloc as they should.
2016-02-08 12:57:41 -06:00
$$(foreach dep,$$(RUST_DEPS_$(1)_T_$(CFG_BUILD)), \
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)) \
mk: Move disable-jemalloc logic into makefiles The `--disable-jemalloc` configure option has a failure mode where it will create a distribution that is not compatible with other compilers. For example the nightly for Linux will assume that it will link to jemalloc by default as an allocator for executable crates. If, however, a standard library is used which was built via `./configure --disable-jemalloc` then this will fail because the jemalloc crate wasn't built. While this seems somewhat reasonable as a niche situation, the same mechanism is used for disabling jemalloc for platforms that just don't support it. For example if the rumprun target is compiled then the sibiling Linux target *also* doesn't have jemalloc. This is currently a problem for our cross-build nightlies which build many targets. If rumprun is also built, it will disable jemalloc for all targets, which isn't desired. This commit moves the platform-specific disabling of jemalloc as hardcoded logic into the makefiles that is scoped per-platform. This way when configuring multiple targets **without the `--disable-jemalloc` option specified** all targets will get jemalloc as they should.
2016-02-08 12:57:41 -06:00
$$(foreach dep,$$(filter $$(DOC_CRATES), $$(RUST_DEPS_$(1)_T_$(CFG_BUILD))), \
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: 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)) \
mk: Pass the same flags to rustdoc as rustc This ensures that def ids don't drift too much over time. Closes #15309
2015-04-06 17:26:27 -05:00
$$(RUSTDOC) --cfg dox --cfg stage2 $$(RUSTFLAGS_$(1)) $$<
Add a compiler-docs target
2013-12-28 23:13:19 -06:00
endef
mk: Stop documenating non-facade crates This commit ceases documentation-by-default of crates such as `term`, `serialize`, and `alloc`. Crates like `term` and `rand` have duplicates on `crates.io` and the search index entries generated in the local tree end up only leading to confusion. Crates like the entire compiler infrastructure, `flate`, or `rbml` don't need to be documented in such a prominent location. This change also means that doc tests will no longer be run for crates beyond the facade (e.g. `serialize` or `term`), but there were very few doc tests in there to begin with. Closes #22168
2015-04-07 17:11:16 -05:00
$(foreach crate,$(CRATES),$(eval $(call DEF_LIB_DOC,$(crate))))
mk: don't build docs for internal or behind-the-facade crates in beta/stable This saves a bunch of a time and will make distributions smaller, as well as avoiding filling the implementors page with internal garbage. Turn it back on with `--enable-compiler-docs` if you want compiler docs during development. Crates behind the facade are only documented on nightly/dev builds (where they can be used). [breaking-change] Closes #23772 Closes #21297
2015-03-27 22:01:19 -05:00
mk: Stop documenating non-facade crates This commit ceases documentation-by-default of crates such as `term`, `serialize`, and `alloc`. Crates like `term` and `rand` have duplicates on `crates.io` and the search index entries generated in the local tree end up only leading to confusion. Crates like the entire compiler infrastructure, `flate`, or `rbml` don't need to be documented in such a prominent location. This change also means that doc tests will no longer be run for crates beyond the facade (e.g. `serialize` or `term`), but there were very few doc tests in there to begin with. Closes #22168
2015-04-07 17:11:16 -05:00
COMPILER_DOC_TARGETS := $(CRATES:%=doc/%/index.html)
mk: fix the CFG_ENABLE_COMPILER_DOCS spelling
2015-06-02 16:49:47 -05:00
ifdef CFG_ENABLE_COMPILER_DOCS
mk: Stop documenating non-facade crates This commit ceases documentation-by-default of crates such as `term`, `serialize`, and `alloc`. Crates like `term` and `rand` have duplicates on `crates.io` and the search index entries generated in the local tree end up only leading to confusion. Crates like the entire compiler infrastructure, `flate`, or `rbml` don't need to be documented in such a prominent location. This change also means that doc tests will no longer be run for crates beyond the facade (e.g. `serialize` or `term`), but there were very few doc tests in there to begin with. Closes #22168
2015-04-07 17:11:16 -05:00
DOC_TARGETS += $(COMPILER_DOC_TARGETS)
else
DOC_TARGETS += $(DOC_CRATES:%=doc/%/index.html)
mk: don't build docs for internal or behind-the-facade crates in beta/stable This saves a bunch of a time and will make distributions smaller, as well as avoiding filling the implementors page with internal garbage. Turn it back on with `--enable-compiler-docs` if you want compiler docs during development. Crates behind the facade are only documented on nightly/dev builds (where they can be used). [breaking-change] Closes #23772 Closes #21297
2015-03-27 22:01:19 -05:00
endif
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)
Introduce 'make doc' -> 'make docs' Because 'doc' is a directory, when running `make doc`, you'll see this: make: Nothing to be done for `doc'. By adding a target for `doc` to build `docs`, both work. Fixes #14705
2015-09-02 17:03:17 -05:00
doc: 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
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
src/doc/trpl -> src/doc/book The book was located under 'src/doc/trpl' because originally, it was going to be hosted under that URL. Late in the game, before 1.0, we decided that /book was a better one, so we changed the output, but not the input. This causes confusion for no good reason. So we'll change the source directory to look like the output directory, like for every other thing in src/doc.
2015-11-19 10:30:18 -06:00
book: 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
src/doc/trpl -> src/doc/book The book was located under 'src/doc/trpl' because originally, it was going to be hosted under that URL. Late in the game, before 1.0, we decided that /book was a better one, so we changed the output, but not the input. This causes confusion for no good reason. So we'll change the source directory to look like the output directory, like for every other thing in src/doc.
2015-11-19 10:30:18 -06:00
doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/book/*.md) | doc/
std: Deprecate std::old_io::fs This commit deprecates the majority of std::old_io::fs in favor of std::fs and its new functionality. Some functions remain non-deprecated but are now behind a feature gate called `old_fs`. These functions will be deprecated once suitable replacements have been implemented. The compiler has been migrated to new `std::fs` and `std::path` APIs where appropriate as part of this change.
2015-02-26 23:00:43 -06:00
@$(call E, rustbook: $@)
"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
src/doc/trpl -> src/doc/book The book was located under 'src/doc/trpl' because originally, it was going to be hosted under that URL. Late in the game, before 1.0, we decided that /book was a better one, so we changed the output, but not the input. This causes confusion for no good reason. So we'll change the source directory to look like the output directory, like for every other thing in src/doc.
2015-11-19 10:30:18 -06:00
$(Q)$(RUSTBOOK) build $(S)src/doc/book doc/book
Import rust-guidlines at https://github.com/rust-lang/rust-guidelines/commit/16fa41b3b091e7e532c809c7145dd88b8e4a5513 Fixes #19315
2015-02-14 11:02:45 -06:00
rename TARPL to The Rustinomicon
2015-07-31 16:13:59 -05:00
nomicon: doc/nomicon/index.html
update build to make tarpl
2015-07-14 01:31:52 -05:00
rename TARPL to The Rustinomicon
2015-07-31 16:13:59 -05:00
doc/nomicon/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/nomicon/*.md) | doc/
update build to make tarpl
2015-07-14 01:31:52 -05:00
@$(call E, rustbook: $@)
rename TARPL to The Rustinomicon
2015-07-31 16:13:59 -05:00
$(Q)rm -rf doc/nomicon
$(Q)$(RUSTBOOK) build $(S)src/doc/nomicon doc/nomicon
update build to make tarpl
2015-07-14 01:31:52 -05:00
Add error index generator.
2015-05-02 19:57:41 -05:00
error-index: doc/error-index.html
Update Makefile
2016-02-07 06:03:11 -06:00
# Metadata used to generate the index is created as a side effect of
# the build so this depends on every crate being up to date.
doc/error-index.html: $(ERR_IDX_GEN_EXE) $(CSREQ$(2)_T_$(CFG_BUILD)_H_$(CFG_BUILD)) | doc/
Rename `error-index-generator` to `error_index_generator` This is because the tool compiler passes the name of the tool as a command line `--cfg`. The improved session config parser is stricter and no longer permits invalid meta items (such as "error-index-generator").
2016-02-15 00:26:37 -06:00
$(Q)$(call E, error_index_generator: $@)
Add error index generator.
2015-05-02 19:57:41 -05:00
$(Q)$(ERR_IDX_GEN)
Update Makefile
2016-02-07 06:03:11 -06:00
doc/error-index.md: $(ERR_IDX_GEN_EXE) $(CSREQ$(2)_T_$(CFG_BUILD)_H_$(CFG_BUILD)) | doc/
Rename `error-index-generator` to `error_index_generator` This is because the tool compiler passes the name of the tool as a command line `--cfg`. The improved session config parser is stricter and no longer permits invalid meta items (such as "error-index-generator").
2016-02-15 00:26:37 -06:00
$(Q)$(call E, error_index_generator: $@)
Update Makefile
2016-02-07 06:03:11 -06:00
$(Q)$(ERR_IDX_GEN_MD)
Reference in New Issue Copy Permalink