Convert sub tutorials into Guides #10838

Ensure configure creates doc/guides directory Fix configure makefile and tests Remove old guides dir and configure option, convert testing to guide Remove ignored files Fix submodule issue prepend dir in makefile so that bor knows how to build the docs S to uppercase
rust-lang · Jan 6, 2014 · eeafee4 · eeafee4 · bors · Jan 6, 2014
1 parent 4bca7fd
commit eeafee4
Show file tree

Hide file tree

Showing 12 changed files with 55 additions and 51 deletions.
diff --git a/configure b/configure
@@ -792,12 +792,12 @@ do
     make_dir $h/test/debug-info
     make_dir $h/test/codegen
     make_dir $h/test/doc-tutorial
-    make_dir $h/test/doc-tutorial-ffi
-    make_dir $h/test/doc-tutorial-macros
-    make_dir $h/test/doc-tutorial-borrowed-ptr
-    make_dir $h/test/doc-tutorial-container
-    make_dir $h/test/doc-tutorial-tasks
-    make_dir $h/test/doc-tutorial-conditions
+    make_dir $h/test/doc-guide-ffi
+    make_dir $h/test/doc-guide-macros
+    make_dir $h/test/doc-guide-borrowed-ptr
+    make_dir $h/test/doc-guide-container
+    make_dir $h/test/doc-guide-tasks
+    make_dir $h/test/doc-guide-conditions
     make_dir $h/test/doc-rust
 done
 

diff --git a/doc/tutorial-borrowed-ptr.md → doc/guide-borrowed-ptr.md b/doc/tutorial-borrowed-ptr.md → doc/guide-borrowed-ptr.md
@@ -1,4 +1,4 @@
-% Rust Borrowed Pointers Tutorial
+% Rust Borrowed Pointers Guide
 
 # Introduction
 

diff --git a/doc/tutorial-conditions.md → doc/guide-conditions.md b/doc/tutorial-conditions.md → doc/guide-conditions.md
@@ -1,4 +1,4 @@
-% Rust Condition and Error-handling Tutorial
+% Rust Condition and Error-handling Guide
 
 # Introduction
 
@@ -12,12 +12,12 @@ The four mechanisms are:
   - Failure
   - Conditions
 
-This tutorial will lead you through use of these mechanisms
+This guide will lead you through use of these mechanisms
 in order to understand the trade-offs of each and relationships between them.
 
 # Example program
 
-This tutorial will be based around an example program
+This guide will be based around an example program
 that attempts to read lines from a file
 consisting of pairs of numbers,
 and then print them back out with slightly different formatting.
@@ -823,7 +823,7 @@ There are three other things to note in this variant of the example program:
 
 # When to use which technique
 
-This tutorial explored several techniques for handling errors.
+This guide explored several techniques for handling errors.
 Each is appropriate to different circumstances:
 
   - If an error may be extremely frequent, expected, and very likely dealt with by an immediate caller,

diff --git a/doc/tutorial-container.md → doc/guide-container.md b/doc/tutorial-container.md → doc/guide-container.md
@@ -1,4 +1,4 @@
-% Containers and iterators
+% Containers and Iterators Guide
 
 # Containers
 

diff --git a/doc/tutorial-ffi.md → doc/guide-ffi.md b/doc/tutorial-ffi.md → doc/guide-ffi.md
@@ -1,8 +1,8 @@
-% Rust Foreign Function Interface Tutorial
+% Rust Foreign Function Interface Guide
 
 # Introduction
 
-This tutorial will use the [snappy](https://code.google.com/p/snappy/)
+This guide will use the [snappy](https://code.google.com/p/snappy/)
 compression/decompression library as an introduction to writing bindings for
 foreign code. Rust is currently unable to call directly into a C++ library, but
 snappy includes a C interface (documented in

diff --git a/doc/tutorial-macros.md → doc/guide-macros.md b/doc/tutorial-macros.md → doc/guide-macros.md
@@ -1,4 +1,4 @@
-% Rust Macros Tutorial
+% Rust Macros Guide
 
 # Introduction
 

diff --git a/doc/tutorial-rustpkg.md → doc/guide-rustpkg.md b/doc/tutorial-rustpkg.md → doc/guide-rustpkg.md
@@ -1,9 +1,9 @@
-% Rust Packaging Tutorial
+% Rust Packaging Guide
 
 # Introduction
 
 Sharing is caring. Rust comes with a tool, `rustpkg`, which allows you to
-package up your Rust code and share it with other people. This tutorial will
+package up your Rust code and share it with other people. This guide will
 get you started on all of the concepts and commands you need to give the gift
 of Rust code to someone else.
 
@@ -92,7 +92,7 @@ There are also default file names you'll want to follow as well:
 Now that you've got workspaces down, let's build your own copy of `hello`. Go
 to wherever you keep your personal projects, and let's make all of the
 directories we'll need. I'll refer to this personal project directory as
-`~/src` for the rest of this tutorial.
+`~/src` for the rest of this guide.
 
 ## Creating our workspace
 

diff --git a/doc/tutorial-tasks.md → doc/guide-tasks.md b/doc/tutorial-tasks.md → doc/guide-tasks.md
@@ -1,10 +1,10 @@
-% Rust Tasks and Communication Tutorial
+% Rust Tasks and Communication Guide
 
 # Introduction
 
 Rust provides safe concurrency through a combination
 of lightweight, memory-isolated tasks and message passing.
-This tutorial will describe the concurrency model in Rust, how it
+This guide will describe the concurrency model in Rust, how it
 relates to the Rust type system, and introduce
 the fundamental library abstractions for constructing concurrent programs.
 

diff --git a/doc/tutorial-testing.md → doc/guide-testing.md b/doc/tutorial-testing.md → doc/guide-testing.md
@@ -1,4 +1,4 @@
-% Rust Testing Tutorial
+% Rust Testing Guide
 
 # Quick start
 

diff --git a/doc/tutorial.md b/doc/tutorial.md
@@ -3035,8 +3035,6 @@ but for this tutorial it's only important to know that you can optionally annota
 extern mod rust = "github.com/mozilla/rust"; // pretend Rust is a simple library
 ~~~
 
-[rustpkg]: rustpkg.html
-
 ## Crate metadata and settings
 
 For every crate you can define a number of metadata items, such as link name, version or author.
@@ -3194,7 +3192,7 @@ re-export a bunch of 'officially blessed' crates that get managed with `rustpkg`
 # What next?
 
 Now that you know the essentials, check out any of the additional
-tutorials on individual topics.
+guides on individual topics.
 
 * [Borrowed pointers][borrow]
 * [Tasks and communication][tasks]
@@ -3209,14 +3207,14 @@ tutorials on individual topics.
 There is further documentation on the [wiki], however those tend to be even
 more out of date than this document.
 
-[borrow]: tutorial-borrowed-ptr.html
-[tasks]: tutorial-tasks.html
-[macros]: tutorial-macros.html
-[ffi]: tutorial-ffi.html
-[container]: tutorial-container.html
-[conditions]: tutorial-conditions.html
-[rustpkg]: tutorial-rustpkg.html
-[testing]: tutorial-testing.html
+[borrow]: guide-borrowed-ptr.html
+[tasks]: guide-tasks.html
+[macros]: guide-macros.html
+[ffi]: guide-ffi.html
+[container]: guide-container.html
+[conditions]: guide-conditions.html
+[rustpkg]: guide-rustpkg.html
+[testing]: guide-testing.html
 [rustdoc]: rustdoc.html
 
 [wiki]: https://github.com/mozilla/rust/wiki/Docs

diff --git a/mk/docs.mk b/mk/docs.mk
@@ -17,7 +17,11 @@ CDOCS :=
 DOCS_L10N :=
 
 BASE_DOC_OPTS := --from=markdown --standalone --toc --number-sections
-HTML_OPTS = $(BASE_DOC_OPTS) --to=html5  --section-divs --css=rust.css  --include-before-body=doc/version_info.html --include-in-header=doc/favicon.inc
+
+HTML_OPTS = $(BASE_DOC_OPTS) 	--to=html5  --section-divs --css=rust.css  \
+															--include-before-body=doc/version_info.html \
+															--include-in-header=doc/favicon.inc
+
 TEX_OPTS = $(BASE_DOC_OPTS) --to=latex
 EPUB_OPTS = $(BASE_DOC_OPTS) --to=epub
 
@@ -112,57 +116,59 @@ doc/l10n/ja/tutorial.html: doc/l10n/ja/tutorial.md doc/version_info.html doc/rus
            --include-before-body=doc/version_info.html \
            --output=$@
 
-DOCS += doc/tutorial-macros.html
-doc/tutorial-macros.html: tutorial-macros.md doc/version_info.html doc/rust.css \
+# Guides
+
+DOCS += doc/guide-macros.html
+doc/guide-macros.html: $(S)doc/guide-macros.md doc/version_info.html doc/rust.css \
 				doc/favicon.inc
 	@$(call E, pandoc: $@)
 	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
 	$(CFG_PANDOC) $(HTML_OPTS) --output=$@
 
-DOCS += doc/tutorial-container.html
-doc/tutorial-container.html: tutorial-container.md doc/version_info.html doc/rust.css \
+DOCS += doc/guide-container.html
+doc/guide-container.html: $(S)doc/guide-container.md doc/version_info.html doc/rust.css \
 				doc/favicon.inc
 	@$(call E, pandoc: $@)
 	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
 	$(CFG_PANDOC) $(HTML_OPTS) --output=$@
 
-DOCS += doc/tutorial-ffi.html
-doc/tutorial-ffi.html: tutorial-ffi.md doc/version_info.html doc/rust.css \
+DOCS += doc/guide-ffi.html
+doc/guide-ffi.html: $(S)doc/guide-ffi.md doc/version_info.html doc/rust.css \
 				doc/favicon.inc
 	@$(call E, pandoc: $@)
 	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
 	$(CFG_PANDOC) $(HTML_OPTS) --output=$@
 
-DOCS += doc/tutorial-testing.html
-doc/tutorial-testing.html: tutorial-testing.md doc/version_info.html doc/rust.css \
+DOCS += doc/guide-testing.html
+doc/guide-testing.html: $(S)doc/guide-testing.md doc/version_info.html doc/rust.css \
 				doc/favicon.inc
 	@$(call E, pandoc: $@)
 	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
 	$(CFG_PANDOC) $(HTML_OPTS) --output=$@
 
-DOCS += doc/tutorial-borrowed-ptr.html
-doc/tutorial-borrowed-ptr.html: tutorial-borrowed-ptr.md doc/version_info.html doc/rust.css \
+DOCS += doc/guide-borrowed-ptr.html
+doc/guide-borrowed-ptr.html: $(S)doc/guide-borrowed-ptr.md doc/version_info.html doc/rust.css \
 				doc/favicon.inc
 	@$(call E, pandoc: $@)
 	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
 	$(CFG_PANDOC) $(HTML_OPTS) --output=$@
 
-DOCS += doc/tutorial-tasks.html
-doc/tutorial-tasks.html: tutorial-tasks.md doc/version_info.html doc/rust.css \
+DOCS += doc/guide-tasks.html
+doc/guide-tasks.html: $(S)doc/guide-tasks.md doc/version_info.html doc/rust.css \
 				doc/favicon.inc
 	@$(call E, pandoc: $@)
 	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
 	$(CFG_PANDOC) $(HTML_OPTS) --output=$@
 
-DOCS += doc/tutorial-conditions.html
-doc/tutorial-conditions.html: tutorial-conditions.md doc/version_info.html doc/rust.css \
+DOCS += doc/guide-conditions.html
+doc/guide-conditions.html: $(S)doc/guide-conditions.md doc/version_info.html doc/rust.css \
 				doc/favicon.inc
 	@$(call E, pandoc: $@)
 	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
 	$(CFG_PANDOC) $(HTML_OPTS) --output=$@
 
-DOCS += doc/tutorial-rustpkg.html
-doc/tutorial-rustpkg.html: tutorial-rustpkg.md doc/version_info.html doc/rust.css \
+DOCS += doc/guide-rustpkg.html
+doc/guide-rustpkg.html: $(S)doc/guide-rustpkg.md doc/version_info.html doc/rust.css \
 				doc/favicon.inc
 	@$(call E, pandoc: $@)
 	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \

diff --git a/mk/tests.mk b/mk/tests.mk
@@ -20,8 +20,8 @@ TEST_HOST_CRATES = rustpkg rustc rustdoc syntax
 TEST_CRATES = $(TEST_TARGET_CRATES) $(TEST_HOST_CRATES)
 
 # Markdown files under doc/ that should have their code extracted and run
-DOC_TEST_NAMES = tutorial tutorial-ffi tutorial-macros tutorial-borrowed-ptr \
-                 tutorial-tasks tutorial-conditions tutorial-container rust
+DOC_TEST_NAMES = tutorial guide-ffi guide-macros guide-borrowed-ptr \
+                 guide-tasks guide-conditions guide-container rust
 
 ######################################################################
 # Environment configuration