[Merged by Bors] - Code validation and format checking

[ghost]

Objective

Migrates #203
Closes #83

Solution

• Add code validation
• Add code format checking Removed to unblock the code validation changes

Problems

During the implementation of the code validation and the format checking I encountered some problems which I would appreciate guidance or help with.

Need to be addressed

1. Zola doesn't highlight the code blocks using the rust syntax if you add more than just the language to the code block attributes. Example rust highlights the code correctly, rust,no_run doesn't. So currently the code highlighting is broken. Zola is order dependent for attributes (as noted by @mockersf). So changing the attribute order from rust,no_run to no_run,rust works just fine.
2. Running cargo fmt doesn't format the doc examples. Adding the rustfmt.toml option format_code_in_doc_comments = true enables this, but requires nightly. In my tests it also only works if you add the code examples directly without using #[doc = include_str!("_index.md")]. So currently the format checking is not working.

Nice to have

1. The lib.rs file of the code-validation crate has to be manually updated each time a new _index.md file is added or removed. It might be a good idea to dive deeper and see if we can implement a solution where this work is done automatically. For now this should be more than fine though.

[alice-i-cecile]

Zola doesn't highlight the code blocks using the rust syntax if you add more than just the language to the code block attributes. Example rust highlights the code correctly, rust,no_run doesn't. So currently the code highlighting is broken.

I'm not seeing an existing issue for this, but the author has been very responsive in the past. Let me make one and see what we can do.

[mockersf]

if I remember correctly, Zola is order dependant for attributes and it should work with no_run,rust

[ghost]

That did the trick. Thank you!

This is important to know for everyone that creates and/or edits code examples. Do we have a place to note this down?

[alice-i-cecile]

Do we have a place to note this down?

IMO we should have a CONTRIBUTING.md for this repo. Can you start one in this PR and note that down?

[alice-i-cecile]

So, the question is: do we want to merge this as is, or block on a code formatting solution. IMO code formatting is the much-less important problem here; and I'd prefer to get this rolling faster to improve book quality and contributor experience.

[mockersf]

2. Running cargo fmt doesn't format the doc examples. Adding the rustfmt.toml option format_code_in_doc_comments = true enables this, but requires nightly. In my tests it also only works if you add the code examples directly without using #[doc = include_str!("_index.md")]. So currently the format checking is not working.

Would it work if you expand the macro then run the formatting?

[ghost]

So, the question is: do we want to merge this as is, or block on a code formatting solution. IMO code formatting is the much-less important problem here; and I'd prefer to get this rolling faster to improve book quality and contributor experience.

Agreed. I sadly couldn't find anything online about the format_code_in_doc_comments setting that verified my findings. Having CI check formatting without ever failing is not the worst thing ever, but if we want to merge this we could also remove the CI task and add it once we find a solution.

Would it work if you expand the macro then run the formatting?

Do you mean expanding the macro so that you get #[doc = "the actual string of the file"]? If that's the case then it didn't work for me. Seems like #[doc = "..."] is not respected by cargo fmt which seems weird, but format_code_in_doc_comments is an unstable feature so who knows.

[alice-i-cecile]

@KDecay IMO we should split out the validation and formatting checks in order to unblock this.

I really really want this in place before I (or others) attempt to write more content for the book.

[ghost]

Definitely agreed. I'll update the CI workflow so it only validates the code.

[alice-i-cecile]

This no longer closes #279, however it does close #83.

[ghost]

Updated the description accordingly.

[IceSentry]

So, just to make sure I understand this correctly. Let's say I want to have a small code block that only shows a few lines that are added to a block that was defined earlier, I would now need to have the entire valid program in the code block and hide all the lines I don't want to show?

[ghost]

@IceSentry Yup. This way we ensure that the code shown to the user is valid. You can also use the ignore tag, but that would defeat the purpose of this change.

[IceSentry]

Right, makes sense, where can I get more information on how the hide-line parameter works?

[alice-i-cecile]

It looks like it's an extension of the rust-doc feature, but I can't immediately see where the hide-line parameter can be found.

[alice-i-cecile]

bors r+

[ghost]

@IceSentry https://www.getzola.org/documentation/content/syntax-highlighting/#annotations

[bors]

Pull request successfully merged into new-book.

Build succeeded:

• build