derive: allow supplying source in comment #127

Kijewski · 2024-08-12T15:47:17Z

Using #[template(source = "…")] is tiresome, because you have to escape the input. That makes it difficult to read, too. Using #[template(path = "…") can be tiresome, too, if the code is small and/or if you just want to prototype something.

This PR adds a third option to supply the source of a template: You can supply the source in the comments of a template. This works similar to doctest. Any rinja block gets extracted, and the combined blocks are the source code of the template.

GuillaumeGomez · 2024-08-12T15:50:04Z

I like the idea! Don't forget to test with /** and #[doc = ""] too. 😉

Kijewski · 2024-08-12T17:03:35Z

I like the idea! Don't forget to test with /** and #[doc = ""] too. 😉

Oof, yeah, my code did not work at all with these two. :) Fixed.

GuillaumeGomez · 2024-08-12T17:44:22Z

Does it work with code examples like:

///     let x = 12;
///
/// `````
/// let x = 12;
/// `````

?

If not, I'd recommend using pulldown-cmark to parse the markdown and extract code blocks from it instead of trying to do it yourself. ;)

Kijewski · 2024-08-12T18:36:37Z

Does it work with code examples like: `````

Oh, I didn't think about this case. Implemented.

GuillaumeGomez · 2024-08-12T18:38:08Z

It's just one of many. Not sure if your code would handle:

/// `````
/// ```rinja
/// {{bla}}
/// ```
/// `````

correctly

Kijewski · 2024-08-12T18:51:11Z

It's just one of many. Not sure if your code would handle:

~~It does. I had to turn one panic into an error so I could add the test.~~

Kijewski · 2024-08-13T02:30:31Z

I use pulldown-cmark, now. It has a different opinion how to interpret ↓, but I guess it knows it better. :)

/// ```rinja
/// `````
/// {{bla}}
/// `````
/// ```

Kijewski · 2024-08-13T08:13:24Z

Should we wait until pulldown-cmark/pulldown-cmark#916 is released to keep our MSRV?

GuillaumeGomez · 2024-08-13T09:48:56Z

Oh that'd be convenient. Another thing I thought about: should we make it an optional feature?

Kijewski · 2024-08-13T15:34:42Z

Another thing I thought about: should we make it an optional feature?

Yes, good call! It will probably stay a very niche feature. What would you call the feature flag? Is "code-in-doc" too long?

GuillaumeGomez · 2024-08-13T15:36:58Z

code-in-doc sounds good to me. 👍

rinja_derive/src/input.rs

+fn collect_comment_blocks(ast: &syn::DeriveInput) -> Option<(Option<Span>, String)> {
+    let mut span: Option<Span> = None;
+    let mut assign_span = |kv: &syn::MetaNameValue| {
+        // FIXME: uncomment once <https://github.com/rust-lang/rust/issues/54725> is stable


GuillaumeGomez · 2024-08-13T18:40:26Z

Oh btw I asked on the pulldown-cmark PR and they said hopefully there should be a release this week. :)

GuillaumeGomez · 2024-08-16T16:36:23Z

New pulldown-cmark version with reduced MSRV has been published.

Kijewski · 2024-08-16T16:45:33Z

error: package pulldown-cmark v0.11.1 cannot be built because it requires rustc 1.71.1 or newer, while the currently active rustc version is 1.71.0

~~I guess it's acceptable if I raise our MSRV by 0.1. :D~~

Well, let's not. If the user does not need the feature, then 1.17.0 is good enough.

rinja_derive/src/input.rs

Kijewski · 2024-08-20T10:03:59Z

Hm, should #[template(in_doc = false)] succeed if the feature is not implemented? I guess yes?

GuillaumeGomez · 2024-08-20T11:48:04Z

I'd say yes.

GuillaumeGomez · 2024-08-20T11:49:40Z

book/src/creating_templates.md

+As an alternative to supplying the code template code in an external file (as `path` argument),
+or as a string (as `source` argument), you can also enable the `"code-in-doc"` feature.
+With this feature, you can specify the template code directly in the documentation
+of the template `struct`.


Suggested change

of the template `struct`.

of the template item.

Because I think we support union or enum (or both). Never remember which.

Kijewski · 2024-08-20T11:49:56Z

I'd say yes.

I already, pro-actively made this case succeed. :)

GuillaumeGomez · 2024-08-20T11:50:04Z

book/src/creating_templates.md

+of the template `struct`.
+
+Instead of `path = "…"` or `source = "…"`, specify `in_doc = true` in the `#[template]` attribute,
+and in the struct's documentation add a ```` ```rinja ```` code block:


Suggested change

and in the struct's documentation add a ```` ```rinja ```` code block:

and in the item's documentation, add a code block with the `rinja` attribute:

GuillaumeGomez · 2024-08-20T11:51:19Z

rinja_actix/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rinja_actix"
-version = "0.3.0"
+version = "0.3.1"


A reason why you're updating versions? Shouldn't it be done in a separate PR?

Because I added a new feature, but it could be done in another PR, too.

It's not the first one. Please do it in another PR then. Like that we make publish it too and also ensure we don't have any other features we want to be merged before making this release.

GuillaumeGomez · 2024-08-20T11:51:50Z

rinja_derive/src/input.rs

-            CompileError::new("template `path` or `source` not found in attributes", None)
+            CompileError::new(
+                #[cfg(not(feature = "code-in-doc"))]
+                "specify one template argument `path` OR `source`",


Maybe let's not put OR in capital? XD

GuillaumeGomez · 2024-08-20T11:52:38Z

rinja_derive/src/input.rs

@@ -422,6 +433,177 @@ impl TemplateArgs {
    }
 }

+/// Try to find the souce in the comment, in a "```rinja```" block


Suggested change

/// Try to find the souce in the comment, in a "```rinja```" block

/// Try to find the souce in the comment, in a `rinja` code block.

GuillaumeGomez · 2024-08-20T11:53:55Z

rinja_derive/src/input.rs

+    let kind = match &ast.data {
+        syn::Data::Struct(_) => "struct",
+        syn::Data::Enum(_) => "enum",
+        syn::Data::Union(_) => "union",


So we do support all item types! 😆

Hehe, I simply added cases for all variant of the enum. I actually don't think that we generate valid code for unions, because I think reading from unions is only allowed in an unsafe context.

Funny. Might worth handling unions correctly at some point.

GuillaumeGomez · 2024-08-20T11:55:00Z

rinja_derive/src/lib.rs

+/// of the template `struct`.
+///
+/// Instead of `path = "…"` or `source = "…"`, specify `in_doc = true` in the `#[template]`
+/// attribute, and in the struct's documentation add a ```` ```rinja ```` code block:


Suggested change

/// attribute, and in the struct's documentation add a ```` ```rinja ```` code block:

/// attribute, and in the struct's documentation add a `rinja` code block:

Kijewski · 2024-08-20T12:07:52Z

All suggestions applied.

GuillaumeGomez · 2024-08-20T12:30:47Z

Thanks a lot, it's a very cool feature! :)

Kijewski · 2024-08-20T12:59:37Z

Thanks! And thank you for your reviews and suggestions! :)

Kijewski force-pushed the pr-code branch from c1a917a to 7a5a888 Compare August 12, 2024 15:48

Kijewski force-pushed the pr-code branch 3 times, most recently from c19e0fa to e801a93 Compare August 12, 2024 17:01

Kijewski force-pushed the pr-code branch from e801a93 to ea74031 Compare August 12, 2024 18:34

Kijewski changed the title ~~derive: allow supplying source in comment~~ derive: allow supplying source in comment (waiting for next pulldown-cmark release) Aug 13, 2024

Kijewski force-pushed the pr-code branch 2 times, most recently from 695bd53 to 3f43e43 Compare August 13, 2024 16:11

Kijewski mentioned this pull request Aug 13, 2024

derive: no panics, less work, more compatibility #132

Merged

Kijewski force-pushed the pr-code branch 2 times, most recently from 61ae0ee to d984cd5 Compare August 13, 2024 18:26

github-advanced-security bot found potential problems Aug 13, 2024

View reviewed changes

Kijewski force-pushed the pr-code branch from d984cd5 to 67fbc5c Compare August 16, 2024 16:43

Kijewski changed the title ~~derive: allow supplying source in comment (waiting for next pulldown-cmark release)~~ derive: allow supplying source in comment Aug 16, 2024

Kijewski marked this pull request as ready for review August 16, 2024 16:49

GuillaumeGomez reviewed Aug 16, 2024

View reviewed changes

rinja_derive/src/input.rs Show resolved Hide resolved

Kijewski added 5 commits August 20, 2024 11:50

derive: use new pulldown-cmark version

ae37754

book: explain "code-in-doc"

41c80ea

derive: add in_doc attribute

42d5810

Update pulldown-cmark

6185778

derive: document in_doc in doc

771f89d

Kijewski force-pushed the pr-code branch from 93eb139 to 3798049 Compare August 20, 2024 10:01

Kijewski force-pushed the pr-code branch 2 times, most recently from f41c0b0 to 90d5a79 Compare August 20, 2024 10:07

Kijewski added 3 commits August 20, 2024 12:09

derive: allow in_doc = false

a7f6a3f

Add feature code_in_doc to integration crates

882e799

Bump version numbers

6d4e3df

Kijewski force-pushed the pr-code branch from 90d5a79 to 6d4e3df Compare August 20, 2024 10:10

GuillaumeGomez reviewed Aug 20, 2024

View reviewed changes

Apply review comments

6cd78ac

Kijewski force-pushed the pr-code branch from a535377 to 6cd78ac Compare August 20, 2024 12:04

GuillaumeGomez approved these changes Aug 20, 2024

View reviewed changes

GuillaumeGomez merged commit 4ef3567 into rinja-rs:master Aug 20, 2024
29 checks passed

Kijewski deleted the pr-code branch August 20, 2024 12:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

derive: allow supplying source in comment #127

derive: allow supplying source in comment #127

Kijewski commented Aug 12, 2024

GuillaumeGomez commented Aug 12, 2024

Kijewski commented Aug 12, 2024

GuillaumeGomez commented Aug 12, 2024

Kijewski commented Aug 12, 2024

GuillaumeGomez commented Aug 12, 2024

Kijewski commented Aug 12, 2024 •

edited

Loading

Kijewski commented Aug 13, 2024

Kijewski commented Aug 13, 2024

GuillaumeGomez commented Aug 13, 2024

Kijewski commented Aug 13, 2024 •

edited

Loading

GuillaumeGomez commented Aug 13, 2024

GuillaumeGomez commented Aug 13, 2024

GuillaumeGomez commented Aug 16, 2024

Kijewski commented Aug 16, 2024 •

edited

Loading

Kijewski commented Aug 20, 2024

GuillaumeGomez commented Aug 20, 2024

GuillaumeGomez Aug 20, 2024

Kijewski commented Aug 20, 2024

GuillaumeGomez Aug 20, 2024

GuillaumeGomez Aug 20, 2024

Kijewski Aug 20, 2024

GuillaumeGomez Aug 20, 2024

GuillaumeGomez Aug 20, 2024

GuillaumeGomez Aug 20, 2024

GuillaumeGomez Aug 20, 2024

Kijewski Aug 20, 2024

GuillaumeGomez Aug 20, 2024

GuillaumeGomez Aug 20, 2024

Kijewski commented Aug 20, 2024

GuillaumeGomez commented Aug 20, 2024

Kijewski commented Aug 20, 2024

	and in the struct's documentation add a ```` ```rinja ```` code block:
	and in the item's documentation, add a code block with the `rinja` attribute:

	/// Try to find the souce in the comment, in a "```rinja```" block
	/// Try to find the souce in the comment, in a `rinja` code block.

	/// attribute, and in the struct's documentation add a ```` ```rinja ```` code block:
	/// attribute, and in the struct's documentation add a `rinja` code block:

derive: allow supplying source in comment #127

derive: allow supplying source in comment #127

Conversation

Kijewski commented Aug 12, 2024

GuillaumeGomez commented Aug 12, 2024

Kijewski commented Aug 12, 2024

GuillaumeGomez commented Aug 12, 2024

Kijewski commented Aug 12, 2024

GuillaumeGomez commented Aug 12, 2024

Kijewski commented Aug 12, 2024 • edited Loading

Kijewski commented Aug 13, 2024

Kijewski commented Aug 13, 2024

GuillaumeGomez commented Aug 13, 2024

Kijewski commented Aug 13, 2024 • edited Loading

GuillaumeGomez commented Aug 13, 2024

GuillaumeGomez commented Aug 13, 2024

GuillaumeGomez commented Aug 16, 2024

Kijewski commented Aug 16, 2024 • edited Loading

Kijewski commented Aug 20, 2024

GuillaumeGomez commented Aug 20, 2024

Choose a reason for hiding this comment

Kijewski commented Aug 20, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Kijewski commented Aug 20, 2024

GuillaumeGomez commented Aug 20, 2024

Kijewski commented Aug 20, 2024

Kijewski commented Aug 12, 2024 •

edited

Loading

Kijewski commented Aug 13, 2024 •

edited

Loading

Kijewski commented Aug 16, 2024 •

edited

Loading