"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.

Author: steveklabnik

README.md

@@ -6,14 +6,14 @@ documentation.
 ## Quick Start
 
 1. Download a [binary installer][installer] for your platform.
-2. Read the [guide].
+2. Read [The Rust Programming Language][trpl].
 3. Enjoy!
 
 > ***Note:*** Windows users can read the detailed
 > [using Rust on Windows][win-wiki] notes on the wiki.
 
 [installer]: http://www.rust-lang.org/install.html
-[guide]: http://doc.rust-lang.org/guide.html
+[trpl]: http://doc.rust-lang.org/book/index.html
 [win-wiki]: https://github.com/rust-lang/rust/wiki/Using-Rust-on-Windows
 
 ## Building from Source
@@ -53,7 +53,7 @@ documentation.
     When complete, `make install` will place several programs into
     `/usr/local/bin`: `rustc`, the Rust compiler, and `rustdoc`, the
     API-documentation tool.
-3. Read the [guide].
+3. Read [The Rust Programming Language][trpl].
 4. Enjoy!
 
 ### Building on Windows
@@ -75,7 +75,7 @@ To easily build on windows we can use [MSYS2](http://sourceforge.net/projects/ms
 
 [repo]: https://github.com/rust-lang/rust
 [tarball]: https://static.rust-lang.org/dist/rust-nightly.tar.gz
-[guide]: http://doc.rust-lang.org/guide.html
+[trpl]: http://doc.rust-lang.org/book/index.html
 
 ## Notes
 

RELEASES.md

@@ -19,8 +19,10 @@ Version 1.0.0-alpha (January 2015)
       distribution into the Cargo ecosystem so they can evolve
       separately and don't need to be stabilized as quickly, including
       'time', 'getopts', 'num', 'regex', and 'term'.
-    * Documentation continues to be expanded with more guides, more
-      API coverage and more examples.
+    * Documentation continues to be expanded with more API coverage, more
+      examples, and more in-depth explanations. The guides have been
+      consolidated into [The Rust Programming Language][trpl].
+    * "Rust By Example" is now maintained by the Rust team.
     * All official Rust binary installers now come with [Cargo], the
       Rust package manager.
 
@@ -179,6 +181,7 @@ Version 1.0.0-alpha (January 2015)
 [objsafe]: https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md
 [assoc]: https://github.com/rust-lang/rfcs/blob/master/text/0195-associated-items.md
 [ints]: https://github.com/rust-lang/rfcs/pull/544#issuecomment-68760871
+[trpl]: http://doc.rust-lang.org/book/index.html
 
 Version 0.12.0 (October 2014)
 -----------------------------

configure

@@ -1055,18 +1055,6 @@ do
     make_dir $h/test/debuginfo-gdb
     make_dir $h/test/debuginfo-lldb
     make_dir $h/test/codegen
-    make_dir $h/test/doc-guide
-    make_dir $h/test/doc-guide-ffi
-    make_dir $h/test/doc-guide-runtime
-    make_dir $h/test/doc-guide-macros
-    make_dir $h/test/doc-guide-ownership
-    make_dir $h/test/doc-guide-pointers
-    make_dir $h/test/doc-guide-container
-    make_dir $h/test/doc-guide-tasks
-    make_dir $h/test/doc-guide-plugin
-    make_dir $h/test/doc-guide-crates
-    make_dir $h/test/doc-guide-error-handling
-    make_dir $h/test/doc-reference
 done
 
 # Configure submodules

mk/crates.mk

@@ -57,7 +57,7 @@ RUSTC_CRATES := rustc rustc_typeck rustc_borrowck rustc_resolve rustc_driver \
                 rustc_trans rustc_back rustc_llvm
 HOST_CRATES := syntax $(RUSTC_CRATES) rustdoc fmt_macros
 CRATES := $(TARGET_CRATES) $(HOST_CRATES)
-TOOLS := compiletest rustdoc rustc
+TOOLS := compiletest rustdoc rustc rustbook
 
 DEPS_core :=
 DEPS_libc := core
@@ -99,9 +99,11 @@ DEPS_fmt_macros = std
 TOOL_DEPS_compiletest := test getopts
 TOOL_DEPS_rustdoc := rustdoc
 TOOL_DEPS_rustc := rustc_driver
+TOOL_DEPS_rustbook := std regex rustdoc
 TOOL_SOURCE_compiletest := $(S)src/compiletest/compiletest.rs
 TOOL_SOURCE_rustdoc := $(S)src/driver/driver.rs
 TOOL_SOURCE_rustc := $(S)src/driver/driver.rs
+TOOL_SOURCE_rustbook := $(S)src/rustbook/main.rs
 
 ONLY_RLIB_core := 1
 ONLY_RLIB_libc := 1

mk/docs.mk

@@ -9,7 +9,7 @@
 # except according to those terms.
 
 ######################################################################
-# The various pieces of standalone documentation: guides, manual, etc
+# The various pieces of standalone documentation.
 #
 # The DOCS variable is their names (with no file extension).
 #
@@ -25,13 +25,11 @@
 # L10N_LANGS are the languages for which the docs have been
 # translated.
 ######################################################################
-DOCS := index intro tutorial guide guide-ffi guide-macros guide-ownership \
-	guide-tasks guide-container guide-pointers guide-testing \
-	guide-plugin guide-crates complement-bugreport guide-error-handling \
-	complement-lang-faq complement-design-faq complement-project-faq \
-    rustdoc guide-unsafe guide-strings reference
+DOCS := index intro tutorial complement-bugreport \
+    complement-lang-faq complement-design-faq complement-project-faq \
+    rustdoc reference
 
-PDF_DOCS := guide reference
+PDF_DOCS := reference
 
 RUSTDOC_DEPS_reference := doc/full-toc.inc
 RUSTDOC_FLAGS_reference := --html-in-header=doc/full-toc.inc
@@ -61,9 +59,15 @@ RUSTDOC_EXE = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
 # ./configure
 RUSTDOC = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTDOC_EXE)
 
+# 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)
+
 D := $(S)src/doc
 
-DOC_TARGETS :=
+DOC_TARGETS := trpl
 COMPILER_DOC_TARGETS :=
 DOC_L10N_TARGETS :=
 
@@ -270,3 +274,10 @@ endif
 
 docs: $(DOC_TARGETS)
 compiler-docs: $(COMPILER_DOC_TARGETS)
+
+trpl: tmp/trpl.ok
+
+tmp/trpl.ok: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md)
+	$(Q)rm -rf doc/book
+	$(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book
+	$(Q)touch $@

mk/prepare.mk

@@ -70,7 +70,7 @@ define PREPARE_MAN
 	$(Q)$(PREPARE_MAN_CMD) $(PREPARE_SOURCE_MAN_DIR)/$(1) $(PREPARE_DEST_MAN_DIR)/$(1)
 endef
 
-PREPARE_TOOLS = $(filter-out compiletest, $(TOOLS))
+PREPARE_TOOLS = $(filter-out compiletest rustbook, $(TOOLS))
 
 
 # $(1) is tool

mk/tests.mk

@@ -147,6 +147,17 @@ else
 CFG_ADB_TEST_DIR=
 endif
 
+# $(1) - name of doc test
+# $(2) - file of the test
+define DOCTEST
+DOC_NAMES := $$(DOC_NAMES) $(1)
+DOCFILE_$(1) := $(2)
+endef
+
+$(foreach doc,$(DOCS), \
+  $(eval $(call DOCTEST,md-$(doc),$(S)src/doc/$(doc).md)))
+$(foreach file,$(wildcard $(S)src/doc/trpl/src/*), \
+  $(eval $(call DOCTEST,$(file:$(S)src/doc/trpl/src/%.md=trpl-%),$(file))))
 
 ######################################################################
 # Main test targets
@@ -292,6 +303,7 @@ tidy:
 		| grep '^$(S)src/rust-installer' -v \
 		| xargs $(CFG_PYTHON) $(S)src/etc/check-binaries.py
 
+
 endif
 
 
@@ -339,8 +351,8 @@ check-stage$(1)-T-$(2)-H-$(3)-doc-crates-exec: \
            check-stage$(1)-T-$(2)-H-$(3)-doc-crate-$$(crate)-exec)
 
 check-stage$(1)-T-$(2)-H-$(3)-doc-exec: \
-        $$(foreach docname,$$(DOCS), \
-           check-stage$(1)-T-$(2)-H-$(3)-doc-$$(docname)-exec)
+        $$(foreach docname,$$(DOC_NAMES), \
+           check-stage$(1)-T-$(2)-H-$(3)-doc-$$(docname)-exec) \
 
 check-stage$(1)-T-$(2)-H-$(3)-pretty-exec: \
 	check-stage$(1)-T-$(2)-H-$(3)-pretty-rpass-exec \
@@ -795,17 +807,18 @@ check-stage$(1)-T-$(2)-H-$(3)-doc-$(4)-exec: $$(call TEST_OK_FILE,$(1),$(2),$(3)
 # rustdoc etc.
 ifeq ($(NO_REBUILD),)
 DOCTESTDEP_$(1)_$(2)_$(3)_$(4) = \
-	$$(D)/$(4).md \
+	$$(DOCFILE_$(4)) \
 	$$(TEST_SREQ$(1)_T_$(2)_H_$(3)) \
 	$$(RUSTDOC_EXE_$(1)_T_$(2)_H_$(3))
 else
-DOCTESTDEP_$(1)_$(2)_$(3)_$(4) = $$(D)/$(4).md
+DOCTESTDEP_$(1)_$(2)_$(3)_$(4) = $$(DOCFILE_$(4))
 endif
 
 ifeq ($(2),$$(CFG_BUILD))
 $$(call TEST_OK_FILE,$(1),$(2),$(3),doc-$(4)): $$(DOCTESTDEP_$(1)_$(2)_$(3)_$(4))
 	@$$(call E, run doc-$(4) [$(2)])
-	$$(Q)$$(RUSTDOC_$(1)_T_$(2)_H_$(3)) --cfg dox --test $$< --test-args "$$(TESTARGS)" && touch $$@
+	$$(Q)$$(RUSTDOC_$(1)_T_$(2)_H_$(3)) --cfg dox --test $$< \
+		--test-args "$$(TESTARGS)" && touch $$@
 else
 $$(call TEST_OK_FILE,$(1),$(2),$(3),doc-$(4)):
 	touch $$@
@@ -815,7 +828,7 @@ endef
 $(foreach host,$(CFG_HOST), \
  $(foreach target,$(CFG_TARGET), \
   $(foreach stage,$(STAGES), \
-   $(foreach docname,$(DOCS), \
+   $(foreach docname,$(DOC_NAMES), \
     $(eval $(call DEF_DOC_TEST,$(stage),$(target),$(host),$(docname)))))))
 
 # Crates
@@ -877,7 +890,7 @@ TEST_GROUPS = \
 	debuginfo-lldb \
 	codegen \
 	doc \
-	$(foreach docname,$(DOCS),doc-$(docname)) \
+	$(foreach docname,$(DOC_NAMES),doc-$(docname)) \
 	pretty \
 	pretty-rpass \
     pretty-rpass-valgrind \
@@ -946,7 +959,7 @@ $(foreach stage,$(STAGES), \
    $(eval $(call DEF_CHECK_FOR_STAGE_AND_HOSTS_AND_GROUP,$(stage),$(host),$(group))))))
 
 define DEF_CHECK_DOC_FOR_STAGE
-check-stage$(1)-docs: $$(foreach docname,$$(DOCS), \
+check-stage$(1)-docs: $$(foreach docname,$$(DOC_NAMES), \
                        check-stage$(1)-T-$$(CFG_BUILD)-H-$$(CFG_BUILD)-doc-$$(docname)) \
                      $$(foreach crate,$$(TEST_DOC_CRATES), \
                        check-stage$(1)-T-$$(CFG_BUILD)-H-$$(CFG_BUILD)-doc-crate-$$(crate))