This is a work in progress, but this should get *extensive* review, so I'm putting it up early and often.
This is the start of a draft of the new 'ownership guide,' which explains ownership, borrowing, etc. I'm feeling better about this framing than last time's, but we'll see.
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.
The Guide isn't 100% perfect, but it's basically complete. It's
certainly better than the tutorial is. Time to start pointing more
people its way.
I also just made it consistent to call all things 'guides' rather than
tutorials.
Fixes#9874. This is the big one.
And two bugs that just go away.
Fixes#14503.
Fixes#15009.
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
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
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
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
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#13593Closes#13787
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.
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
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>
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.
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
`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.
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.
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.
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
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.
