Stream: rustdoc

Topic: Getting active features in rustdoc::render


view this post on Zulip Poliorcetics (Nov 28 2020 at 01:12):

Currently working on https://github.com/rust-lang/rust/pull/79454. I need to gate the new parsing to the feature but I don't know how to check if a feature is currently active when the code asking for the check is in librustdoc, not directly in the compiler

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:14):

I have found https://rustc-dev-guide.rust-lang.org/implementing_new_features.html and https://rustc-dev-guide.rust-lang.org/feature-gates.html#adding-a-feature-gate in the dev guide but they seem to need either a tcx or sess which I don't know how to get when in librustdoc

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:16):

@Poliorcetics cx.tcx

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:16):

is this in render? render doesn't have a tcx available unfortunately

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:17):

this is in html/markdown.rs

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:17):

In an iterator impl

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:17):

so yeah unfortunately there's no tcx there

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:18):

I need to get around to adding it - it should be fairly simple, just lift the call to enter_compiler up to main instead of putting it in core

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:18):

in the meantime, you can store the info you need in DocContext

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:19):

err no sorry, DocContext goes away by the time you get to render

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:19):

hmmm

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:20):

renderInfo maybe? https://github.com/rust-lang/rust/blob/master/src/librustdoc/lib.rs#L481

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:20):

or renderOptions? I don't know the difference

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:20):

@GuillaumeGomez do you?

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:21):

Oh wait I'm having another problem before that:

I declared the new feature as explained in the dev guide in active.rs:

    /// Allows users to provide classes for fenced code block using `class:classname`.
    (active, user_classes_in_docs, "1.50.0", Some(79483), None),

But now I get this error:

   Compiling rustc_feature v0.0.0 (/Users/alexis/Projects/rust/rust/compiler/rustc_feature)
error[E0425]: cannot find value `user_classes_in_docs` in module `sym`
   --> compiler/rustc_feature/src/active.rs:624:14
    |
624 |     (active, user_classes_in_docs, "1.50.0", Some(79483), None),
    |              ^^^^^^^^^^^^^^^^^^^^ not found in `sym`

error[E0531]: cannot find unit struct, unit variant or constant `user_classes_in_docs` in module `sym`
   --> compiler/rustc_feature/src/active.rs:624:14
    |
624 |     (active, user_classes_in_docs, "1.50.0", Some(79483), None),
    |              ^^^^^^^^^^^^^^^^^^^^ not found in `sym`

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:22):

I looked at the sym module and I can't understand it at all

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:23):

And the PR I also use as a guide did not touch it so I'm not sure how to do it

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:23):

you need to add it here: https://github.com/rust-lang/rust/blob/master/compiler/rustc_span/src/symbol.rs#L105

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:23):

sym is for interned strings

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:23):

ohhhh, thanks !

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:24):

specifically, strings that are interned at compile time and can be used statically without having to intern it again

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:26):

argh, recompiling half the world now

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:26):

Well, at least it seems to compile :grinning:

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:29):

Barring compilation times, I'm always surprised by how nice it is to contribute to rust-lang/rust

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:32):

error: ui test compiled successfully! :laughter_tears:

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:33):

you need // check-pass at the top

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:33):

This is intended to fail, this is the test for the missing feature gate ^^

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:34):

So now I'm back to the original problem, how to know if the feature is active or not

view this post on Zulip Poliorcetics (Nov 28 2020 at 01:35):

I'm modifying the LangString::parse method

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:35):

I would guess you need to thread the info through RenderInfo somehow

view this post on Zulip Joshua Nelson (Nov 28 2020 at 01:36):

but I don't know much about this part of rustdoc

view this post on Zulip Poliorcetics (Nov 28 2020 at 23:28):

I could add a new lint to passes/doc_test_lints.rs ? Elsewhere, even if I detect an incorrect use, I cannot report it properly

view this post on Zulip Joshua Nelson (Nov 28 2020 at 23:40):

oh I see

view this post on Zulip Joshua Nelson (Nov 28 2020 at 23:40):

yeah that's unfortunate

view this post on Zulip Joshua Nelson (Nov 28 2020 at 23:41):

checking it ahead of time seems reasonable

view this post on Zulip Joshua Nelson (Nov 28 2020 at 23:42):

although this is enough of a hack I'm wondering if we should just pass in a tcx to render after all

view this post on Zulip Joshua Nelson (Nov 28 2020 at 23:42):

it's not that much less work at this point

view this post on Zulip Poliorcetics (Nov 28 2020 at 23:50):

It's even more of a hack no ? Errors related to parsing probably should appear from render ?

view this post on Zulip Poliorcetics (Nov 28 2020 at 23:50):

I'm going to try the lint route

view this post on Zulip Joshua Nelson (Nov 28 2020 at 23:51):

well there shouldn't be a difference between render and clean

view this post on Zulip Joshua Nelson (Nov 28 2020 at 23:51):

https://github.com/rust-lang/rust/issues/76382

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:18):

error[E0658]: Found in 2 block(s): class:test:name, class:test2, class:test3
 --> src/main.rs:1:1
  |
1 | / /// Some code block with `rust,class:test:name` as the language string
2 | | ///
3 | | /// ```rust,class:test:name
4 | | /// int main(void) { return 0; }
... |
8 | | /// int main(void) { return 0; }
9 | | /// ```
  | |_______^
  |
  = note: see issue #79483 <https://github.com/rust-lang/rust/issues/79483> for more information
  = help: add `#![feature(custom_code_classes_in_docs)]` to the crate attributes to enable

error: aborting due to previous error

For more information about this error, try `rustc --explain E0658`.
error: could not document `playground`

Caused by:
  process didn't exit successfully: `rustdoc --edition=2018 --crate-type bin --crate-name playground src/main.rs -o /Users/alexis/Projects/rust/playground/target/doc --error-format=json --json=diagnostic-rendered-ansi --document-private-items -L dependency=/Users/alexis/Projects/rust/playground/target/debug/deps --crate-version 0.1.0` (exit code: 1)

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:19):

It works !

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:19):

Successfully fails to compile*

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:20):

And doesn't warn with the #![feature(custom_code_classes_in_docs)] present

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:20):

nice

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:20):

nice :D

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:24):

Is there a way to warn about individual doc examples ?

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:24):

Since here I am warning about something outside of the example but relevant to only it, not the whole doc-comment

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:24):

like within a doc-comment? not that I know of, @GuillaumeGomez might know

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:25):

If it's not possible the current solution is probably the best I can do

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:25):

I.E listing the class:... items and saying they should be in this comment

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:34):

I'm having trouble with the feature gate test

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:34):

what sort of trouble?

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:34):

I cannot place it in src/test/ui since it compiles correctly but does not run rustdoc

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:34):

put it in src/test/rustdoc-ui instead

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:35):

And in src/test/rustdoc-ui it complains about missing the test for it in src/test/ui

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:35):

oh that seems like a bug in tidy

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:35):

what's the complaint it gives?

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:35):

Expected a gate test for the feature 'custom_code_classes_in_docs'.
Hint: create a failing test file named 'feature-gate-custom_code_classes_in_docs.rs'
      in the 'ui' test suite, with its failures due to
      missing usage of `#![feature(custom_code_classes_in_docs)]`.
Hint: If you already have such a test and don't want to rename it,
      you can also add a // gate-test-custom_code_classes_in_docs line to the test file.
tidy error: Found 1 features without a gate test.
some tidy checks failed


command did not execute successfully: "/Users/alexis/Projects/rust/rust/build/x86_64-apple-darwin/stage0-tools-bin/tidy" "/Users/alexis/Projects/rust/rust" "/Users/alexis/Projects/rust/rust/build/x86_64-apple-darwin/stage0/bin/cargo" "/Users/alexis/Projects/rust/rust/build"
expected success, got: exit code: 1


failed to run: /Users/alexis/Projects/rust/rust/build/bootstrap/debug/bootstrap test --stage 1 --test-args feature-gate-custom_code_c
Build completed unsuccessfully in 0:00:08

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:36):

My test file is src/test/rustdoc-ui/feature-gate-custom_code_classes_in_docs.rs

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:36):

did you try // gate-test-custom_code_classes_in_docs in rustdoc-ui?

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:36):

No yet, I didn't think it was necessary

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:36):

I'll try that

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:36):

if that doesn't work, tidy probably needs to be changed to look in more directories

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:38):

Nop, doesn't work

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:39):

ok, then you'll need to fix tidy unfortunately

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:39):

it's somewhere in src/tools IIRC

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:40):

look for "src/test/ui"

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:41):

actually maybe ask in #t-compiler/help

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:43):

Found it :smile:

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:45):

Hum, looks like I worsened my situation, now I don't get an error at all despite the missing .stderr file

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:45):

tidy is probably not running rustdoc on the file

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:45):

@simulacrum do you have suggestions for how to add a feature gate that only appears for rustdoc?

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:45):

we can't put the test in src/test/ui because it doesn't fail there

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:45):

and src/test/rustdoc-ui appears to be ignored

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:46):

And for code in /// comments, not code considered by rustc

view this post on Zulip simulacrum (Nov 29 2020 at 01:46):

I doubt you want to force people to write e.g. #![cfg_attr(...)] for it -- is there a reason it needs to be only a rustdoc feature?

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:46):

because it doesn't exist otherwise

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:46):

it's for how language strings are parsed in markdown comments

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:46):

and rustc completely ignores comments

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:47):

/// Some code block with `rust,class:test:name` as the language string
///
/// ```rust,class:test:name
/// int main(void) {
///     return 0;
/// }
/// ```
fn main() {}

The idea is to gate the class:test:name above to nightly

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:47):

I'm not sure what cfg_attr has to do with it

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:48):

So far I have a working error message but cannot ensure it works with tidy, i'm supposing it doesn't run rustdoc on feature gates files (logical given this is not important for 433 out of 434 features)

view this post on Zulip simulacrum (Nov 29 2020 at 01:49):

I just mean that there should be no reason the feature gate can't just be defined for all things

view this post on Zulip simulacrum (Nov 29 2020 at 01:49):

rustc can do nothing for it, but that should be fine

view this post on Zulip simulacrum (Nov 29 2020 at 01:49):

rustdoc will do something...

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:49):

well sure, but it seems silly to add a test that does nothing

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:49):

rustdoc never gets run on src/test/ui

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:49):

so it won't fail to compile

view this post on Zulip simulacrum (Nov 29 2020 at 01:50):

why do you need to add a test?

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:50):

because tidy enforces it :laughing:

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:50):

To ensure it's only usable on nightly too ^^

view this post on Zulip simulacrum (Nov 29 2020 at 01:50):

just... edit tidy?

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:50):

I'm doing this

view this post on Zulip Joshua Nelson (Nov 29 2020 at 01:51):

simulacrum said:

just... edit tidy?

well, is it ok to say 'you no longer need a test for all features'?

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:51):

Is running rustdoc on tests in rustdoc-ui only ok ? That way the other 433 features shouldn't pay the cost

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:51):

And all features would still be tested

view this post on Zulip simulacrum (Nov 29 2020 at 01:51):

I personally am not too worried by having a test that tidy can't currently see

view this post on Zulip simulacrum (Nov 29 2020 at 01:51):

It's a lint tool, sometimes it is wrong

view this post on Zulip simulacrum (Nov 29 2020 at 01:51):

If you want to adjust tidy to support gate tests in rustdoc-ui that seems fine too.

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:52):

Will do that then !

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:53):

Oh wait ! Tidy doesn't catch it but running the whole test suite does

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:53):

Because rustdoc is run on files in rustdoc-ui later in the process

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:53):

So a one-line modif to tidy and running the whole test suite makes it work

view this post on Zulip Poliorcetics (Nov 29 2020 at 01:54):

I'll explain that in a comment on the tidy modif else I'll forget it

view this post on Zulip Poliorcetics (Nov 29 2020 at 02:07):

Well, now I have another problem:

---- [ui] rustdoc-ui/feature-gate-custom_code_classes_in_docs.rs stdout ----

error: /Users/alexis/Projects/rust/rust/src/test/rustdoc-ui/feature-gate-custom_code_classes_in_docs.rs:1: unexpected error: '1:1: 3:8: Found in 1 block(s): class:language-c [E0658]'

error: 1 unexpected errors found, 0 expected errors not found
status: exit code: 1
command: "/Users/alexis/Projects/rust/rust/build/x86_64-apple-darwin/stage1/bin/rustdoc" "/Users/alexis/Projects/rust/rust/src/test/rustdoc-ui/feature-gate-custom_code_classes_in_docs.rs" "-Zthreads=1" "--target=x86_64-apple-darwin" "--error-format" "json" "-Zui-testing" "-Zdeduplicate-diagnostics=no" "-Zemit-future-incompat-report" "-o" "/Users/alexis/Projects/rust/rust/build/x86_64-apple-darwin/test/rustdoc-ui/feature-gate-custom_code_classes_in_docs" "-Cdebuginfo=0" "-Zunstable-options" "-Lnative=/Users/alexis/Projects/rust/rust/build/x86_64-apple-darwin/native/rust-test-helpers" "-L" "/Users/alexis/Projects/rust/rust/build/x86_64-apple-darwin/test/rustdoc-ui/feature-gate-custom_code_classes_in_docs/auxiliary"
unexpected errors (from JSON output): [
    Error {
        line_num: 1,
        kind: Some(
            Error,
        ),
        msg: "1:1: 3:8: Found in 1 block(s): class:language-c [E0658]",
    },
]

thread '[ui] rustdoc-ui/feature-gate-custom_code_classes_in_docs.rs' panicked at 'explicit panic', src/tools/compiletest/src/runtest.rs:1493:13
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

view this post on Zulip Poliorcetics (Nov 29 2020 at 02:07):

This is caused by the JSON format output

view this post on Zulip Joshua Nelson (Nov 29 2020 at 02:07):

you need to add an error annotation

view this post on Zulip Joshua Nelson (Nov 29 2020 at 02:07):

https://rustc-dev-guide.rust-lang.org/tests/adding.html#ui

view this post on Zulip Poliorcetics (Nov 29 2020 at 02:33):

Well, 3h33AM is a good hour to go to sleep now that is works

view this post on Zulip Poliorcetics (Nov 29 2020 at 02:33):

Pushed my changes, let's hope CI will confirm I didn't miss anything


Last updated: Oct 11 2021 at 22:34 UTC