Hidden code in examples is not hidden when display on Zola

[alice-i-cecile]

In Rust doc tests, you can use the # line prefix to hide lines. This prevents them from showing up in your helpful minimal explanations, and allows you to avoid repetitive boilerplate or tests.

In #295, I tried to do the same thing, as our examples our currently compiled. However, this does not work:

Fixing this is critical for the new book release: we either need to enable hiding in some form or figure out an alternate approach to compiling examples.

[alice-i-cecile]

@devil-ira points out that we can use Zola's annotations.

[cart]

Specifying hidden lines at the top / decoupled from the code in question feels like a great way to accidentally hide the wrong thing when you change code. If we're importing code blocks from a separate file I'm guessing we could use a short code to strip out those lines. But for inline rust we're probably stuck with what zola offers. Maybe they'd accept a PR that special cases rust code :)

[Nilirad]

Can this be considered a bug? A bug is a non intended behavior in an existing feature, but in our case that feature doesn't even exist.

Also, can this be labeled as blocked upstream?

[doup]

Would a CLI tool that either lints (e.g. hide_lines must match with # lines) or writes the Zola annotations be useful? I imagine this being used as part of CI, pre-commit hook or maybe just by Alice as some manual QA.

I started to do this as Rust practice and I've the lint part quite advanced… knowing that this could be used would motivate me to finish it… 😅

[alice-i-cecile]

Yes, I would very much like that :) It would need to be integrated with CI, and I'd prefer if it had a --fix mode that wrote the annotations.

[cart]

Yeah that seems like a solid middle ground solution while we wait. Worth calling out that it would make it harder to preview your work in a WYSIWYG way with zola serve though, which feels like a reasonably sized loss.

[doup]

I could finally put some time into this, in the end I went directly for the formatting. I don't how this should be integrated, another folder on the repo? (like code-validation, generate-assets…) or, maybe as a cargo binary? What do you think? 🤔

https://github.com/doup/zola_rustdoc_hide_lines

You can run it with cargo run -- data, and it should modify data/example.md.