Add relative-path macros

[heaths]

Requires Rust version 1.88.0 or newer.

[heaths]

I defined a rust_analyzer cfg to work around rust-lang/rust-analyzer#15950 for now. In VSCode, rust-analyzer will define the rust_analyzer cfg to avoid showing errors in tests/readme.rs or elsewhere as needed.

[heaths]

Might be worth implementing a polyfill strategy like proc-macro2 did for its Span::local_file(). That way I could define the macros regardless an err appropriately when < 1.88.0.

[heaths]

@LarryOsterman what do you think about having macros that support relative paths (to the source file that includes the macro) for Rust version >= 1.88 when, to support 1.85 (our MSRV), I have to support Cargo.toml-relative paths anyway? It was an interesting problem to work on - especially how to get rust-analyzer to stop showing errors because it doesn't implement Span::local_file() - but not convinced it's worth the maintenance cost or even the confusion it may cause for people on Rust versions < 1.88.

[LarryOsterman]

@LarryOsterman what do you think about having macros that support relative paths (to the source file that includes the macro) for Rust version >= 1.88 when, to support 1.85 (our MSRV), I have to support Cargo.toml-relative paths anyway? It was an interesting problem to work on - especially how to get rust-analyzer to stop showing errors because it doesn't implement Span::local_file() - but not convinced it's worth the maintenance cost or even the confusion it may cause for people on Rust versions < 1.88.

I have mixed feelings - it seems like a nice addition, but it's weird that it requires a separate macro - IMHO that makes it less useful. And I suspect that the base functionality is probably sufficient for now.

[heaths]

Maybe I could support both ways. If I set the floor (practically a chroot) to the crate directory, if you start with a period I could assume a relative path to the source file IIF you're on 1.88 or return an Err; otherwise, assume relative to the crate root i.e.,

• (1.88) "./README.md" relative to source file
• (<1.88) "./README.md" -> Err("nuh uh uh")
• "README.md" relative to crate root
• "tests/README.adoc" relative to crate root

Or maybe that's just too magical.

[LarryOsterman]

Maybe I could support both ways. If I set the floor (practically a chroot) to the crate directory, if you start with a period I could assume a relative path to the source file IIF you're on 1.88 or return an Err; otherwise, assume relative to the crate root i.e.,

• (1.88) "./README.md" relative to source file
• (<1.88) "./README.md" -> Err("nuh uh uh")
• "README.md" relative to crate root
• "tests/README.adoc" relative to crate root

Or maybe that's just too magical.

Actually, except for the 1.88 thingy, this seems to be pretty close to exactly what I'd want :) And the 1.88 thing could be manageable. The only real challenge there ensuring that we don't do rustdoc tests on the MSRV pipeline until we update MSRV to be 1.88 or beyond.

[heaths]

Actually, except for the 1.88 thingy, this seems to be pretty close to exactly what I'd want :) And the 1.88 thing could be manageable. The only real challenge there ensuring that we don't do rustdoc tests on the MSRV pipeline until we update MSRV to be 1.88 or beyond.

That shouldn't matter, though. If we use crate root-relative paths - no preceding "." - it'll work regardless of the rustc version. If/when we update to >= 1.88 and it seems easier to manage to make them relative to the source file like include_str!(), then we could.

[heaths]

@LarryOsterman @RickWinter @analogrelay I have another idea: named parameters with or without values just like serde et. al. I could add scope to automatically put the fragment into its own code block like I did in Azure/azure-sdk-for-rust#3337 and clean up calling code, and another called relative or something that denotes relative paths or fails if <= rustc 1.88. Thoughts?

[heaths]

Replaced by PR #29