search

rust-unofficial / patterns

A catalogue of Rust design patterns, anti-patterns and idioms
https://rust-unofficial.github.io/patterns/
Mozilla Public License 2.0
7.98k stars 363 forks source link

Check code formatting of examples in CI #118

Open MarcoIeni opened 3 years ago

MarcoIeni commented 3 years ago

Is this possible with rustfmt and mdbook?

simonsan commented 3 years ago

Opened an upstream issue: https://github.com/rust-lang/mdBook/issues/1422

MarcoIeni commented 3 years ago

I removed this from "To do" in Rust Patterns because it is blocked by upstream.

simonsan commented 3 years ago

An idea would be to extract the code and put them in specific example files like ffi-export.rs and include this file/parts of this file with the following syntax:

https://rust-lang.github.io/mdBook/format/mdbook.html#including-files

That would make it possible to actually check the files, have better examples people can compile directly and we can run cargo fmt and cargo check on them if we want to.

Downside of it is that it's a bit more work to include it in the markdown but the upside is that we separate actual code examples from the documentation. What are your thoughts about it?

MarcoIeni commented 3 years ago

Having code examples in the markdown is super handy. I don't think it's worth it.

What about extracting the code examples from markdown with a script, and run rustfmt on them individually?

pickfire commented 3 years ago

But is it possible to check the code samples in the docs while keeping it inlined? I don't think it is useful to separate code samples for a book.

simonsan commented 3 years ago

I'm not aware of any solution that checks the Rust code formatting inline in Markdown nor extracting the code and formatting it on-the-flow and writing it back to the exact same position, hence I thought this could be a solution.

But indeed, not a comfortable one. For the book itself the code examples would be inline, for the markdown they would not be inline anymore.

As I think the most important part in this is now the book itself, I don't have much of a problem separating code from text if it makes linting, formatting and compiling easier.

Also another advantage: We would be able to have running programs, where people could pick out portions of that file to further explain them in the markdown. And if people would like to run a more complete example, they could compile it with (e.g.) cargo run --example builder.

The disadvantage with this kind of separation is if we edit code examples we need to update the lines in the markdown file as well. EDIT: We wouldn't need to with anchors: To avoid breaking your book when modifying included files, you can also include a specific section using anchors instead of line numbers.

I'm not quite sure if this wouldn't be the overall better long-term solution, though. In my imagination it would be much cleaner for this repository while the book itself would look the same. Is there anything else I might be overlooking here?

EDIT2: https://github.com/PsichiX/md-bakery seems also interesting, maybe not for our use case, just for me as a reminder