This commit adds a crate-level dashboard summarizing the stability
levels of all items for all submodules of the crate.
The information is also written as a json file, intended for consumption
by pages like http://huonw.github.io/isrustfastyet/Closes#13541
- Treat WOFF as binary files so that git does not perform newline normalization.
- Replace corrupt Heuristica files with Source Serif Pro — italics are [almost in production](https://github.com/adobe/source-serif-pro/issues/2) so I left Heuristica Italic which makes a good pair with SSP. Overall, Source Serif Pro is I think a better fit for rustdoc (cc @TheHydroImpulse). This ought to fix#15527.
- Store Source Code Pro locally in order to make offline docs freestanding. Fixes#14778.
Preview: http://adrientetar.legtux.org/cached/rust-docs/core.html
r? @alexcrichton
This commit hooks rustdoc into the stability index infrastructure in two
ways:
1. It looks up stability levels via the index, rather than by manual
attributes.
2. It adds stability level information throughout rustdoc output, rather
than just at the top header. In particular, a stability color (with
mouseover text) appears next to essentially every item that appears
in rustdoc's HTML output.
Along the way, the stability index code has been lightly refactored.
Replace its usage with byte string literals, except in `bytes!()` tests.
Also add a new snapshot, to be able to use the new b"foo" syntax.
The src/etc/2014-06-rewrite-bytes-macros.py script automatically
rewrites `bytes!()` invocations into byte string literals.
Pass it filenames as arguments to generate a diff that you can inspect,
or `--apply` followed by filenames to apply the changes in place.
Diffs can be piped into `tip` or `pygmentize -l diff` for coloring.
* Change links to display:block for click larger targets
* Remove linebreaks due to extra space
* Adjust margins so that element spacing stays the same
* Sidebar item hover background colour chosen from <pre> styling
* The select/plural methods from format strings are removed
* The # character no longer needs to be escaped
* The \-based escapes have been removed
* '{{' is now an escape for '{'
* '}}' is now an escape for '}'
Closes#14810
[breaking-change]
This commit is the final step in the libstd facade, #13851. The purpose of this
commit is to move libsync underneath the standard library, behind the facade.
This will allow core primitives like channels, queues, and atomics to all live
in the same location.
There were a few notable changes and a few breaking changes as part of this
movement:
* The `Vec` and `String` types are reexported at the top level of libcollections
* The `unreachable!()` macro was copied to libcore
* The `std::rt::thread` module was moved to librustrt, but it is still
reexported at the same location.
* The `std::comm` module was moved to libsync
* The `sync::comm` module was moved under `sync::comm`, and renamed to `duplex`.
It is now a private module with types/functions being reexported under
`sync::comm`. This is a breaking change for any existing users of duplex
streams.
* All concurrent queues/deques were moved directly under libsync. They are also
all marked with #![experimental] for now if they are public.
* The `task_pool` and `future` modules no longer live in libsync, but rather
live under `std::sync`. They will forever live at this location, but they may
move to libsync if the `std::task` module moves as well.
[breaking-change]
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
This commit carries out the request from issue #14678:
> The method `Iterator::len()` is surprising, as all the other uses of
> `len()` do not consume the value. `len()` would make more sense to be
> called `count()`, but that would collide with the current
> `Iterator::count(|T| -> bool) -> unit` method. That method, however, is
> a bit redundant, and can be easily replaced with
> `iter.filter(|x| x < 5).count()`.
> After this change, we could then define the `len()` method
> on `iter::ExactSize`.
Closes#14678.
[breaking-change]
Cross crate links can target items which are not rendered in the documentation.
If the item is reexported at a higher level, the destination of the link (a
concatenation of the fully qualified name) may actually lead to nowhere. This
fixes this problem by altering rustdoc to emit pages which redirect to the local
copy of the reexported structure.
cc #14515Closes#14137
This commit adds support in rustdoc to recognize the `#[doc(primitive = "foo")]`
attribute. This attribute indicates that the current module is the "owner" of
the primitive type `foo`. For rustdoc, this means that the doc-comment for the
module is the doc-comment for the primitive type, plus a signal to all
downstream crates that hyperlinks for primitive types will be directed at the
crate containing the `#[doc]` directive.
Additionally, rustdoc will favor crates closest to the one being documented
which "implements the primitive type". For example, documentation of libcore
links to libcore for primitive types, but documentation for libstd and beyond
all links to libstd for primitive types.
This change involves no compiler modifications, it is purely a rustdoc change.
The landing pages for the primitive types primarily serve to show a list of
implemented traits for the primitive type itself.
The primitive types documented includes both strings and slices in a semi-ad-hoc
way, but in a way that should provide at least somewhat meaningful
documentation.
Closes#14474
When inlining documentation across crates, primitive implementors of traits were
not shown. This commit tweaks the infrastructure to treat primitive and
Path-like impls the same way, displaying all implementors everywhere.
cc #14462
Instead of one giant function, this breaks it up into several smaller functions
which have explicit dependencies among one another.
There are no code changes as a result of this commit.
Previously this was adding one-too-many `..`s to the path for the
`gotosrc=...` links for local crates. Also, the `root_path` already ends
in `/`s so a trailing / shouldn't be added after the root (some servers
treat `...//...` different to `.../...` including the one running
doc.rust-lang.org).
These links work by hyperlinking back to the actual documentation page with a
query parameter which will be recognized and then auto-click the appropriate
[src] link.
Within the documentation for a crate, all hyperlinks to reexported items don't
go across crates, but rather to the items in the crate itself. This will allow
references to Option in the standard library to link to the standard library's
Option, instead of libcore's.
This does mean that other crate's links for Option will still link to libcore's
Option.
This commit teaches rustdoc to inline the documentation for the destination of a
`pub use` statement across crate boundaries. This is intended for the standard
library's facade to show the fact that the facade is just an implementation
detail rather than the api of the standard library itself.
This starts out by inlining traits and functions, but more items will come soon.
The current drawback of this system is that hyperlinks across crates sill go to
the original item's definition rather than the reexported location.
This commit alters rustdoc to crawl the metadata of upstream libraries in order
to fill in default methods for traits implemented in downstream crates. This,
for example, documents the `insert` function on hash maps.
This is a fairly lossy extraction from the metadata. Documentation and
attributes are lost, but they aren't used anyway. Unfortunately, argument names
are also lost because they are not present in the metadata. Source links are
also lost because the spans are not serialized.
While not perfect, it appears that presenting this documentation through rustdoc
is much better than nothing, so I wanted to land this to allow iteration on it
later on.
Right now, when you look in the "Implementors" section for traits, you only see
implementors within that crate. This commit modifies that section to include
implementors from neighboring crates as well.
For example, the Container trait currently says that it is only implemented by
strings and slices, but it is in fact implemented by nearly all containers.
Implementation-wise, this change generates an "implementors cache" similarly to
the search index where each crate will append implementors to the files. When
the page for a trait is loaded, it will load its specific cache file, rendering
links for all upstream types which implement the trait.
1. Wherever the `buf` field of a `Formatter` was used, the `Formatter` is used
instead.
2. The usage of `write_fmt` is minimized as much as possible, the `write!` macro
is preferred wherever possible.
3. Usage of `fmt::write` is minimized, favoring the `write!` macro instead.
This commit brings the local_data api up to modern rust standards with a few key
improvements:
* The `pop` and `set` methods have been combined into one method, `replace`
* The `get_mut` method has been removed. All interior mutability should be done
through `RefCell`.
* All functionality is now exposed as a method on the keys themselves. Instead
of importing std::local_data, you now use "key.replace()" and "key.get()".
* All closures have been removed in favor of RAII functionality. This means that
get() and get_mut() no long require closures, but rather return
Option<SmartPointer> where the smart pointer takes care of relinquishing the
borrow and also implements the necessary Deref traits
* The modify() function was removed to cut the local_data interface down to its
bare essentials (similarly to how RefCell removed set/get).
[breaking-change]
This commit removes the inherited documentation from type pages. This generally
just clutters up the page when you can click through to the trait itself to get
all the meaty documentation.
Closes#11991
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
It reflected the obsolete syntax `use a, b, c;` and did not make past the parser (though it was a non-fatal error so we can continue). This legacy affected many portions of rustc and rustdoc as well, so this PR cleans them up altogether.
As a side effect of cleanup, we now have `SCHEMA_VERSION` in `rustdoc::clean` (instead of the crate root), so it has a better chance to be updated when `rustdoc::clean` gets updated.
it reflected the obsolete syntax `use a, b, c;` and did not make
past the parser (though it was a non-fatal error so we can continue).
this legacy affected many portions of rustc and rustdoc as well,
so this commit cleans them up altogether.
The fields of tuple structs recently gained the ability to have privacy
associated with them, but rustdoc was not updated accodingly. This moves the
struct field filtering to the rendering phase in order to preserve the ordering
of struct fields to allow tuple structs to have their private fields printed as
underscores.
Closes#13594
Since the items roughly follow the lexical order, there are
many consecutive items with the same path value which can be
easily compressed.
For the library and compiler docs, this commit decreases
the index size by 26% and 6% before and after gzip, respectively.
`buildIndex` JS function recovers them into the original object form.
This greatly reduces the size of the uncompressed search index (27%),
while this effect is less visible after gzipped (~5%).
libstd: Implement `StrBuf`, a new string buffer type like `Vec`, and port all code over to use it.
Rebased & tests-fixed version of https://github.com/mozilla/rust/pull/13269
Rendered form available at http://docs.octayn.net/doc/
This moves derived impls to the bottom of the list, separate from the rest,
and collapses default methods that aren't overridden into an expandible
accordion.
This needs to be removed as part of removing `~[T]`. Partial type hints
are now allowed, and will remove the need to add a version of this
method for `Vec<T>`. For now, this involves a few workarounds for
partial type hints not completely working.
A major discoverability issue with rustdoc is that all crates have their
documentation built in isolation, so it's difficult when looking at the
documentation for libstd to learn that there's a libcollections crate with a
HashMap in it.
This commit moves rustdoc a little closer to improving the multiple crate
experience. This unifies all search indexes for all crates into one file so all
pages share the same search index. This allows searching to work across crates
in the same documentation directory (as the standard distribution is currently
built).
This strategy involves updating a shared file amongst many rustdoc processes, so
I implemented a simple file locking API for handling synchronization for updates
to the shared files.
cc #12554
The `~str` type is not long for this world as it will be superseded by the
soon-to-come DST changes for the language. The new type will be
`~Str`, and matching over the allocation will no longer be supported.
Matching on `&str` will continue to work, in both a pre and post DST world.
Previously the :hover rules were making the links to the traits/types in
something like
impl<K: Hash + Eq, V> ... { ... }
be displayed with a trailing `§` when hovered over. This commit
restricts that behaviour to specific headers, i.e. those that are known
to be section headers (like those rendered in markdown doc-comments, and
the "Modules", "Functions" etc. headings).
This avoids having to include JS in the guide/tutorial/manual pages just
to get the headers being links. The on-hover behaviour showing the
little section marker § is preserved, because that gives a useful hint
that the heading is a link.
A structure's definition and implementation may be cross-module. If the
implementing module is parsed before defining module, the fully
qualified name of the structure won't be present for the implementation
to use when being indexed. So caches such 'orphan' implementation and
indexes it at the end of crate parsing.
Closes#10284.
This leverages the new hashing framework and hashmap implementation to provide a
much speedier hashing algorithm for node ids and def ids. The hash algorithm
used is currentl FNV hashing, but it's quite easy to swap out.
I originally implemented hashing as the identity function, but this actually
ended up in slowing down rustc compiling libstd from 8s to 13s. I would suspect
that this is a result of a large number of collisions.
With FNV hashing, we get these timings (compiling with --no-trans, in seconds):
| | before | after |
|-----------|---------:|--------:|
| libstd | 8.324 | 6.703 |
| stdtest | 47.674 | 46.857 |
| libsyntax | 9.918 | 8.400 |
This commit adds a appear-on-over link to all section headers to generated
documentation. Each header also receives an id now, even those generated through
markdown. The purpose of this is to provide easy to link to sections.
This modifies the default header markdown generation because the default id
added looks like "toc_NN" which is difficult to reconcile among all sections (by
default each section gets a "toc_0" id), and it's also not very descriptive of
where you're going.
This chooses to adopt the github-style anchors by taking the contents of the
title and hyphen-separating them (after lower casing).
Closes#12681
Macro definitions are just their raw source code, and so should be
highlighted where possible. Also, $ident non-terminal substitutions are
special, and so are worth of a little special treatment.
There's a lot of these types in the compiler libraries, and a few of the
older or private stdlib ones. Some types are obviously meant to be
public, others not so much.
This adds simple syntax highlighting based off libsyntax's lexer to be sure to
stay up to date with rust's grammar. Some of the highlighting is a bit ad-hoc,
but it definitely seems to get the job done!
This currently doesn't highlight rustdoc-rendered function signatures and
structs that are emitted to each page because the colors already signify what's
clickable and I think we'd have to figure out a different scheme before
colorizing them. This does, however, colorize all code examples and source code.
Closes#11393
