Commit Graph

123 Commits

Author SHA1 Message Date
Alex Crichton
a491551597 rustc: Print a smaller hash on -v
The long hash just takes up space and you can discover the main hash through the
`rustc --version verbose` command.
2014-07-21 09:54:10 -07:00
Steve Klabnik
0c30e1faad Include Strings guide with the others.
Three small changes:

1. Re-organize headers in the Strings guide so they show up correctly.
2. build the strings guide with the other docs
3. include the strings guide in the list of guides
2014-07-18 10:48:24 -04:00
zzmp
63afc08262 Allow external html in rustdoc for crates.
Updated documentation to reflect md->html.
Modularized external file loading.
2014-06-30 00:03:34 -07:00
Steve Klabnik
3ed78f5b6b Add the Guide, add warning to tutorial.
In line with what @brson, @cmr, @nikomatsakis and I discussed this morning, my
redux of the tutorial will be implemented as the Guide. This way, I can work in
small iterations, rather than dropping a huge PR, which is hard to review.  In
addition, the community can observe my work as I'm doing it.

This adds a note in line with [this comment][reddit] that clarifies the state
of the tutorial, and the community's involvement with it.

[reddit]: http://www.reddit.com/r/rust/comments/28bew8/rusts_documentation_is_about_to_drastically/ci9c98k
2014-06-24 17:22:50 -07:00
Steve Klabnik
e16a87513a Remove the cheat sheet.
Rust by Example is far better.

Fixes #14380.
2014-06-24 17:22:39 -07:00
Alex Crichton
992a2db1fc 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 13:00:18 -07:00
Alex Crichton
e5bbbca33e 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 20:00:16 -07:00
Alex Crichton
890754794c mk: Less noisy rustdoc invocations 2014-06-01 21:53:43 -07:00
Luqman Aden
213d54e06c mk: Don't build any docs with --disable-docs. 2014-05-27 20:17:17 -04:00
Corey Richardson
11c0f77107 doc: add a new language design faq
This indends to help quell frequently answered questions about the language
design in a single, authoritative place.
2014-05-25 02:53:53 -07:00
Alex Crichton
799ddba8da Change static.rust-lang.org to doc.rust-lang.org
The new documentation site has shorter urls, gzip'd content, and index.html
redirecting functionality.
2014-05-21 19:55:39 -07:00
Richo Healey
b05af1f6a8 Render not_found with an absolute path to the rust stylesheet 2014-05-15 13:50:45 -07:00
Richo Healey
ef23fa17c3 docs: Add a not found page 2014-05-13 17:24:07 -07:00
Alex Crichton
1547caf748 rustdoc: Fix inclusion of the new fonts
These fonts were moved into place by rust's makefiles, but rustdoc is widely
used outside of rustc itself. This moves the fonts into the rustdoc binary,
similarly to the other static assets, and writes them to the output location
whenever rustdoc generates documentation.

Closes #13593
Closes #13787
2014-05-03 02:09:29 -07:00
Adrien Tétar
c9d995d384 doc,rustdoc: store webfonts locally
- Avoids cross-domain requests restrictions
- Better availability of content
- No HTML queries needed for an offline build
2014-04-25 17:05:56 +09:00
bors
8a4ffbf625 auto merge of #13416 : brson/rust/30min, r=alexcrichton
This is intended to be the first thing somebody new to the language reads about Rust. It is supposed to be simple and intriguing, to give the user an idea of whether Rust is appropriate for them, and to hint that there's a lot of cool stuff to learn if they just keep diving deeper.

I'm particularly happy with the sequence of concurrency examples.
2014-04-15 06:02:06 -07:00
Kang Seonghoon
dd00bf3791 mk: Add a dummy CFG_COMPILER_HOST_TRIPLE to rustdoc invocation.
Otherwise it will prohibit `make compiler-docs` on Windows.
2014-04-10 15:21:59 -07:00
Brian Anderson
ad66f56afd doc: Add "A 30-minute Introduction to Rust"
By Steve Klabnik.
2014-04-09 17:43:26 -07:00
Alex Crichton
78937b9779 std: Document builtin syntax extensions
These syntax extensions need a place to be documented, and this starts passing a
`--cfg dox` parameter to `rustdoc` when building and testing documentation in
order to document macros so that they have no effect on the compiled crate, but
only documentation.

Closes #5605
2014-04-03 16:17:48 -07:00
Jan Kobler
e91115feed verify-grammar path to rust.md
When calling

   make verify-grammar

rust.md cannot be found, because the
path to rust.md is missing.

The path is set to:

   $(D)/rust.md

This can only be tested, when llnextgen is installed.

Signed-off-by: Jan Kobler <eng1@koblersystems.de>
2014-03-27 10:20:30 +01:00
Huon Wilson
3d6c28acd0 docs: begin a "low-level & unsafe code" guide.
This aims to cover the basics of writing safe unsafe code. At the moment
it is just designed to be a better place for the `asm!()` docs than the
detailed release notes wiki page, and I took the time to write up some
other things.

More examples are needed, especially of things that can subtly go wrong;
and vast areas of `unsafe`-ty aren't covered, e.g. `static mut`s and
thread-safety in general.
2014-03-15 13:51:53 +11:00
Alex Crichton
3f2434eee3 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 15:01:27 -07:00
Alex Crichton
1a7e55f4f5 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 15:01:25 -07:00
Adrien Tétar
840a2701ac doc: remove outdated tutorial entry, restore removed Makefile entries 2014-03-11 17:56:40 +01:00
Adrien Tétar
7ec1eb8ab3 doc: auto-generate LaTeX includes 2014-03-11 17:56:32 +01:00
Adrien Tétar
9eadcacdd7 doc: have a real switch b/w LaTeX compilers 2014-03-09 18:44:59 +01:00
Adrien Tétar
862acedf51 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 13:45:36 +01:00
Huon Wilson
b4815ad1ba 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-09 20:59:43 +11:00
Huon Wilson
bb8ac2159f docs: render rustdoc docs with rustdoc, hack around sundown code-fence
parsing limitations.

Sundown parses

    ```
    ~~~

as a valid codeblock (i.e. mismatching delimiters), which made using
rustdoc on its own documentation impossible (since it used nested
codeblocks to demonstrate how testable codesnippets worked).

This modifies those snippets so that they're delimited by indentation,
but this then means they're tested by `rustdoc --test` & rendered as
Rust code (because there's no way to add `notrust` to
indentation-delimited code blocks). A comment is added to stop the
compiler reading the text too closely, but this unfortunately has to be
visible in the final docs, since that's the text on which the
highlighting happens.
2014-03-09 20:59:43 +11:00
Huon Wilson
f7833215b0 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-09 19:34:40 +11:00
bors
b66ec3483b auto merge of #12114 : brson/rust/faqs, r=cmr
These are ancient. I removed a bunch of questions that are less relevant - or completely unrelevant, updated other entries, and removed things that are already better expressed elsewhere.
2014-02-08 20:01:27 -08:00
Brian Anderson
30dcc8285b doc: Modernize FAQs just slightly 2014-02-08 00:38:00 -08:00
Adrien Tétar
ec2f047aa9 doc: add license information for gen. files 2014-02-07 20:50:15 +01:00
bors
a27934c555 auto merge of #12076 : alexcrichton/rust/rpath-makefile-dep, r=thestinger
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 19:16:34 -08:00
Alex Crichton
80920da6b9 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 16:33:41 -08:00
Alex Crichton
454882dcb7 Remove std::condition
This has been a long time coming. Conditions in rust were initially envisioned
as being a good alternative to error code return pattern. The idea is that all
errors are fatal-by-default, and you can opt-in to handling the error by
registering an error handler.

While sounding nice, conditions ended up having some unforseen shortcomings:

* Actually handling an error has some very awkward syntax:

    let mut result = None;
    let mut answer = None;
    io::io_error::cond.trap(|e| { result = Some(e) }).inside(|| {
        answer = Some(some_io_operation());
    });
    match result {
        Some(err) => { /* hit an I/O error */ }
        None => {
            let answer = answer.unwrap();
            /* deal with the result of I/O */
        }
    }

  This pattern can certainly use functions like io::result, but at its core
  actually handling conditions is fairly difficult

* The "zero value" of a function is often confusing. One of the main ideas
  behind using conditions was to change the signature of I/O functions. Instead
  of read_be_u32() returning a result, it returned a u32. Errors were notified
  via a condition, and if you caught the condition you understood that the "zero
  value" returned is actually a garbage value. These zero values are often
  difficult to understand, however.

  One case of this is the read_bytes() function. The function takes an integer
  length of the amount of bytes to read, and returns an array of that size. The
  array may actually be shorter, however, if an error occurred.

  Another case is fs::stat(). The theoretical "zero value" is a blank stat
  struct, but it's a little awkward to create and return a zero'd out stat
  struct on a call to stat().

  In general, the return value of functions that can raise error are much more
  natural when using a Result as opposed to an always-usable zero-value.

* Conditions impose a necessary runtime requirement on *all* I/O. In theory I/O
  is as simple as calling read() and write(), but using conditions imposed the
  restriction that a rust local task was required if you wanted to catch errors
  with I/O. While certainly an surmountable difficulty, this was always a bit of
  a thorn in the side of conditions.

* Functions raising conditions are not always clear that they are raising
  conditions. This suffers a similar problem to exceptions where you don't
  actually know whether a function raises a condition or not. The documentation
  likely explains, but if someone retroactively adds a condition to a function
  there's nothing forcing upstream users to acknowledge a new point of task
  failure.

* Libaries using I/O are not guaranteed to correctly raise on conditions when an
  error occurs. In developing various I/O libraries, it's much easier to just
  return `None` from a read rather than raising an error. The silent contract of
  "don't raise on EOF" was a little difficult to understand and threw a wrench
  into the answer of the question "when do I raise a condition?"

Many of these difficulties can be overcome through documentation, examples, and
general practice. In the end, all of these difficulties added together ended up
being too overwhelming and improving various aspects didn't end up helping that
much.

A result-based I/O error handling strategy also has shortcomings, but the
cognitive burden is much smaller. The tooling necessary to make this strategy as
usable as conditions were is much smaller than the tooling necessary for
conditions.

Perhaps conditions may manifest themselves as a future entity, but for now
we're going to remove them from the standard library.

Closes #9795
Closes #8968
2014-02-06 15:48:56 -08:00
Alex Crichton
22a421fa02 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-02-02 10:59:27 -08:00
Corey Richardson
25fe2cadb1 Remove rustpkg.
I'm sorry :'(

Closes #11859
2014-02-02 03:08:56 -05:00
Alex Crichton
2611483894 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-26 00:53:41 -08:00
Adrien Tétar
b2cac497e8 doc: fix version stamp for TeX files
This fixes a regression introduced in
3d57b240ab.
2014-01-17 19:38:51 +01:00
Alex Crichton
289ba105ae dox: Write a guide to the rust runtime 2014-01-13 23:22:07 -08:00
Kevin Ballard
110e5dd1ac doc: build the docs for librustpkg 2014-01-11 19:13:59 -08:00
Adrien Tétar
72794094a1 Trim src/ README, bring back version_info everywhere 2014-01-11 19:55:24 +01:00
Alex Crichton
b1eaeb5561 doc: build the docs for librustuv
Closes #11444
2014-01-10 15:12:06 -08:00
Steve Klabnik
6f09d80f97 Add Pointer tutorial, rename borrowed pointer tutorial. 2014-01-06 19:37:26 -08:00
Brian Anderson
f5ee07792e mk: Fix formatting of docs.mk 2014-01-06 17:24:16 -08:00
Alan Andrade
7de2379013 rust_version.html is a HTML_DEPS and every html has it as dependecy 2014-01-06 15:38:20 -06:00
Alan Andrade
e53b5661a7 First phase of migrating the wiki to the internal docs #11078 2014-01-06 15:27:49 -06:00
Alan Andrade
eeafee4c9b 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
2014-01-05 22:48:19 -06:00
Julia Evans
f0322371dd Add testing tutorial to docs 2013-12-31 10:34:55 -05:00