mirror of https://github.com/rust-lang/rust.git
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
This commit is contained in:
Alan Andrade
parent
4bca7fdf9b
commit
eeafee4c9b
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
% Rust Borrowed Pointers Tutorial
|
||||
% Rust Borrowed Pointers Guide
|
||||
|
||||
# Introduction
|
||||
|
||||
|
|
@ -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,
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
% Containers and iterators
|
||||
% Containers and Iterators Guide
|
||||
|
||||
# Containers
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
% Rust Macros Tutorial
|
||||
% Rust Macros Guide
|
||||
|
||||
# Introduction
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
% Rust Testing Tutorial
|
||||
% Rust Testing Guide
|
||||
|
||||
# Quick start
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
40
mk/docs.mk
40
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 $< | \
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue