-
Notifications
You must be signed in to change notification settings - Fork 12.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[rustdoc] Add no-hidden-lines
codeblock attribute
#118711
base: master
Are you sure you want to change the base?
[rustdoc] Add no-hidden-lines
codeblock attribute
#118711
Conversation
This comment has been minimized.
This comment has been minimized.
Wouldn't it be simpler to have disambiguator so that you could still hide (for example your imports) ? Using your example it wouldn't be possible to show //! ```rust,raw
//! # use crate::test; // this should be hidden
//!
//! test!(
//! #a, // but not thoses
//! ##b,
//! ###c
//! );
//! ``` |
Macros are a nightmare on their own. You could very well have: //! ```rust,raw
//! # use crate::test; // this should be hidden
//!
//! test!(
//! # use something::other;
//! );
//! ``` |
Not really. It should be more descriptive, like
I'm curious how this will interact with Would turning syntax highlighting off entirely be an acceptable compromise? On the one hand, syntax highlighting doesn't seem very helpful with a huge macro DSL anyway, since rustdoc won't know anything about the syntax of the macro, but, on the other hand, it might work fine if the macro embeds lots of normal Rust code (or is intentionally designed to use Rust keywords for its own keywords instead of making them up). |
Using |
That's what it looks like to me, too, though I can't find any test cases for that (should probably add one). I know #78917 wanted a way to have doctested code without syntax highlighting. Is there any way to do that right now? |
No, doctests are only rust codeblocks. And rust codeblocks have syntax highlighting. |
That's weird... #78917 wanted to turn syntax highlighting off while leaving doctesting on (though they still wanted hidden lines). So, reading through that issue again, I guess |
Indeed. I'll also use the opportunity to rebase to fix the CI failure. |
25061a1
to
d7fa81a
Compare
raw
codeblock attributeno-hidden-lines
codeblock attribute
Could not assign reviewer from: |
…r extra `#` characters
d7fa81a
to
dcf973f
Compare
Renamed the codeblock attribute to |
// @matches - '//*[@class="rust rust-example-rendered"]/code' '\(\s+#a,\s+##b,\s+###c\s+\);' | ||
// @snapshot 'codeblock' - '//*[@class="rust rust-example-rendered"]/code' | ||
|
||
//! ```rust,no_hidden_lines |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see that this isn't gated behind a feature flag. Is that intentional?
(I'm fine either way, but if it's going to be insta-stable then it's going to need to go through an FCP.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's what I want indeed but in any case I'd like us to go through FCP so every one can check it.
@rfcbot fcp merge |
Team member @notriddle has proposed to merge this. The next step is review by the rest of the tagged team members: Concerns:
Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up! See this document for info about what commands tagged team members can give me. |
@rfcbot concern why is this insta stable? Otherwise this looks good |
It seemed small enough to me (it's a new codeblock attribute for a very specific use-case). If it's an issue I can put it behind a feature. Just seems not worth it. |
From the docs, line hiding only occurs on |
@rfcbot concern is-this-a-bug I'm not convinced the behavior where indented pound symbols are hidden is not a bug. I didn't even know we did that, I always thought it only applied to lines that start with a pound symbol. If we were designing the feature today I would have been pretty strongly against having it apply to all pound signs regardless of indentation. It would be somewhat breaking but it's worth figuring out how many crates out there actually use this when indented. |
dcf973f
to
c989304
Compare
That's why I went with
I can send a PR tomorrow removing this behaviour so we can make a crater run. |
… r=<try> Remove weird handling of ## in code examples As mentioned in rust-lang#118711, the handling of `##` in code blocks in code examples is very surprising. Let's see if crates are using it with a crater run. r? `@notriddle`
… r=<try> Remove weird handling of ## in code examples As mentioned in rust-lang#118711, the handling of `##` in code blocks in code examples is very surprising. Let's see if crates are using it with a crater run. r? `@notriddle`
☔ The latest upstream changes (presumably #118900) made this pull request unmergeable. Please resolve the merge conflicts. |
Fixes #118027.
Motivation
When documentation macro and proc-macro, there is currently an extra layer of complexity to take into account when it uses
#
characters. Allowing to disable this rustdoc behaviour with a codeblock attribute would make this task much simpler for (proc) macro documentation writers.Example from #118027:
in documentation codeblocks becomes:
Generating invalid documentation for end users.
What is this feature about?
It is about adding a new
no-hidden-lines
codeblock attribute which would remove this#
character cleanup pass in order to make it easier for (proc) macro API to have code examples.The
no-hidden-lines
attribute works just likeshould_panic
orignore
attributes: if there are no other tags, it'll consider the code block as a rust one and hence will test it.Example of usage:
Concerns
no-hidden-lines
the right name for this codeblock attribute?r? @notriddle