| Age | Commit message (Collapse) | Author | Lines |
|---|
|
|
|
Rustdoc markdown handling is currently split between:
- html::markdown, which contains all the meaty login
- markdown, which is only used for when rustdoc renders a standalone
markdown file
Adds module-level doc-comment to markdown, and rename the function so
it's clear that it's doing IO (instead of just rendering to a string).
|
|
|
|
This commit adds the headers for the top level documentation to
rustdoc's existing table of contents, along with associated items.
It only show two levels of headers. Going further would require the
sidebar to be wider, and that seems unnecessary (the crates that
have manually-built TOCs usually don't need deeply nested headers).
|
|
|
|
GuillaumeGomez:stabilize-custom_code_classes_in_docs, r=rustdoc
Stabilize `custom_code_classes_in_docs` feature
Fixes #79483.
This feature has been around for quite some time now, I think it's fine to stabilize it now.
## Summary
## What is the feature about?
In short, this PR changes two things, both related to codeblocks in doc comments in Rust documentation:
* Allow to disable generation of `language-*` CSS classes with the `custom` attribute.
* Add your own CSS classes to a code block so that you can use other tools to highlight them.
#### The `custom` attribute
Let's start with the new `custom` attribute: it will disable the generation of the `language-*` CSS class on the generated HTML code block. For example:
```rust
/// ```custom,c
/// int main(void) {
/// return 0;
/// }
/// ```
```
The generated HTML code block will not have `class="language-c"` because the `custom` attribute has been set. The `custom` attribute becomes especially useful with the other thing added by this feature: adding your own CSS classes.
#### Adding your own CSS classes
The second part of this feature is to allow users to add CSS classes themselves so that they can then add a JS library which will do it (like `highlight.js` or `prism.js`), allowing to support highlighting for other languages than Rust without increasing burden on rustdoc. To disable the automatic `language-*` CSS class generation, you need to use the `custom` attribute as well.
This allow users to write the following:
```rust
/// Some code block with `{class=language-c}` as the language string.
///
/// ```custom,{class=language-c}
/// int main(void) {
/// return 0;
/// }
/// ```
fn main() {}
```
This will notably produce the following HTML:
```html
<pre class="language-c">
int main(void) {
return 0;
}</pre>
```
Instead of:
```html
<pre class="rust rust-example-rendered">
<span class="ident">int</span> <span class="ident">main</span>(<span class="ident">void</span>) {
<span class="kw">return</span> <span class="number">0</span>;
}
</pre>
```
To be noted, we could have written `{.language-c}` to achieve the same result. `.` and `class=` have the same effect.
One last syntax point: content between parens (`(like this)`) is now considered as comment and is not taken into account at all.
In addition to this, I added an `unknown` field into `LangString` (the parsed code block "attribute") because of cases like this:
```rust
/// ```custom,class:language-c
/// main;
/// ```
pub fn foo() {}
```
Without this `unknown` field, it would generate in the DOM: `<pre class="language-class:language-c language-c">`, which is quite bad. So instead, it now stores all unknown tags into the `unknown` field and use the first one as "language". So in this case, since there is no unknown tag, it'll simply generate `<pre class="language-c">`. I added tests to cover this.
EDIT(camelid): This description is out-of-date. Using `custom,class:language-c` will generate the output `<pre class="language-class:language-c">` as would be expected; it treats `class:language-c` as just the name of a language (similar to the langstring `c` or `js` or what have you) since it does not use the designed class syntax.
Finally, I added a parser for the codeblock attributes to make it much easier to maintain. It'll be pretty easy to extend.
As to why this syntax for adding attributes was picked: it's [Pandoc's syntax](https://pandoc.org/MANUAL.html#extension-fenced_code_attributes). Even if it seems clunkier in some cases, it's extensible, and most third-party Markdown renderers are smart enough to ignore Pandoc's brace-delimited attributes (from [this comment](https://github.com/rust-lang/rust/pull/110800#issuecomment-1522044456)).
r? `@notriddle`
|
|
|
|
|
|
files for arguments if there are too many
|
|
Most notably, this commit changes the `pub use crate::*;` in that file
to `use crate::*;`. This requires a lot of `use` items in other crates
to be adjusted, because everything defined within `rustc_span::*` was
also available via `rustc_span::source_map::*`, which is bizarre.
The commit also removes `SourceMap::span_to_relative_line_string`, which
is unused.
|
|
Co-authored-by: Michael Howell <michael@notriddle.com>
|
|
when its syntax is used.
|
|
|
|
|
|
|
|
MDN directly recommends this in <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link>,
since "CSS is the only stylesheet language used on the web."
Like 07a243b2a46384235d7e2c08688978b7cf018973, but a few places that were
missed the first time.
|
|
By moving `RenderOptions` out of `Option`, because the two structs' uses
are almost entirely separate.
The only complication is that `unstable_features` is needed in both
structs, but it's a tiny `Copy` type so its duplication seems fine.
|
|
rustc's startup has several layers, including:
- `interface::run_compiler` passes a closure, `f`, to
`run_in_thread_pool_with_globals`, which creates a thread pool, sets
up session globals, and passes `f` to `create_compiler_and_run`.
- `create_compiler_and_run` creates a `Session`, a `Compiler`, sets the
source map, and calls `f`.
rustdoc is a bit different.
- `main_args` calls `main_options` via
`run_in_thread_pool_with_globals`, which (again) creates a thread pool
(hardcoded to a single thread!) and sets up session globals.
- `main_options` has four different paths.
- The second one calls `interface::run_compiler`, which redoes the
`run_in_thread_pool_with_globals`! This is bad.
- The fourth one calls `interface::create_compiler_and_run`, which is
reasonable.
- The first and third ones don't do anything of note involving the
above functions, except for some symbol interning which requires
session globals.
In other words, rustdoc calls into `rustc_interface` at three different
levels. It's a bit confused, and feels like code where functionality has
been added by different people at different times without fully
understanding how the globally accessible stuff is set up.
This commit tidies things up. It removes the
`run_in_thread_pool_with_globals` call in `main_args`, and adjust the
four paths in `main_options` as follows.
- `markdown::test` calls `test::test_main`, which provides its own
parallelism and so doesn't need a thread pool. It had one small use of
symbol interning, which required session globals, but the commit
removes this.
- `doctest::run` already calls `interface::run_compiler`, so it doesn't
need further adjustment.
- `markdown::render` is simple but needs session globals for interning
(which can't easily be removed), so it's now wrapped in
`create_session_globals_then`.
- The fourth path now uses `interface::run_compiler`, which is
equivalent to the old `run_in_thread_pool_with_globals` +
`create_compiler_and_run` pairing.
|
|
|
|
|
|
This updates the standard library's documentation to use the new syntax. The
documentation is worthwhile to update as it should be more idiomatic
(particularly for features like this, which are nice for users to get acquainted
with). The general codebase is likely more hassle than benefit to update: it'll
hurt git blame, and generally updates can be done by folks updating the code if
(and when) that makes things more readable with the new format.
A few places in the compiler and library code are updated (mostly just due to
already having been done when this commit was first authored).
|
|
It seems to apply to all doctests in the crate.
|
|
This can be replicated in full with other existing features, there's no
need to have a separate option for it.
This also fixes a bug where `--test-args=--show-output` had no effect,
and updates the documentation.
|
|
|
|
|
|
- Avoid multiple <h1>s on a page.
- The <h#> tags should follow a semantic hierarchy.
- Cap at h6 (no h7)
|
|
|
|
|
|
|
|
This is leftover from when `doctest` used to be called `test`. Remove it
now, it's unnecessary and makes the code harder to read.
|
|
|
|
This gives warnings about dead code.
|
|
The main change is that `UnstableOptions::from_environment` now requires
an (optional) crate name. If the crate name is unknown (`None`), then the new feature is not available and you still have to use `RUSTC_BOOTSTRAP=1`. In practice this means the feature is only available for `--crate-name`, not for `#![crate_name]`; I'm interested in supporting the second but I'm not sure how.
Other major changes:
- Added `Session::is_nightly_build()`, which uses the `crate_name` of
the session
- Added `nightly_options::match_is_nightly_build`, a convenience method
for looking up `--crate-name` from CLI arguments.
`Session::is_nightly_build()`should be preferred where possible, since
it will take into account `#![crate_name]` (I think).
- Added `unstable_features` to `rustdoc::RenderOptions`
There is a user-facing change here: things like `RUSTC_BOOTSTRAP=0` no
longer active nightly features. In practice this shouldn't be a big
deal, since `RUSTC_BOOTSTRAP` is the opposite of stable and everyone
uses `RUSTC_BOOTSTRAP=1` anyway.
- Add tests
Check against `Cheat`, not whether nightly features are allowed.
Nightly features are always allowed on the nightly channel.
- Only call `is_nightly_build()` once within a function
- Use booleans consistently for rustc_incremental
Sessions can't be passed through threads, so `read_file` couldn't take a
session. To be consistent, also take a boolean in `write_file_header`.
|
|
This modules contains the implementation of doctests, and not the
tests of rustdoc itself. This name is confusing, so let's rename it to
doctest for clarity.
|
|
to avoid surprising listed in API guidelines.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Replace file_stem by file_name in rustdoc markdown
Before this PR, a file name like `some.file.md` will be output to a file named `some.html` with is not correct because the expected output file must be `some.file.html`
|
|
|
|
updated and augmented tests in html/markdown.rs
|
|
|
