doc: create macros to hide logo/icon

[comphead]

          thanks @mbrobbel WDYT if we create our own proc macro in `datafusion/macros`?

So the proc macro will eventually generate the inner doc!, so we can improve readability and have logo urls in a single place

Originally posted by @comphead in #14746 (review)

[mbrobbel]

I looked at this briefly, but couldn't make inner attributes work with a proc macro.

[comphead]

I looked at this briefly, but couldn't make inner attributes work with a proc macro.

HI @mbrobbel do you mean proc macros cannot be applied on underlying objects? afaik it is a limited set of object proc macros can be applied on like structs, enums, etc

[mbrobbel]

I looked at this briefly, but couldn't make inner attributes work with a proc macro.

HI @mbrobbel do you mean proc macros cannot be applied on underlying objects? afaik it is a limited set of object proc macros can be applied on like structs, enums, etc

My first attempt was to use a function-like proc macro:

#[proc_macro]
pub fn doc_cfg(_input: TokenStream) -> TokenStream {
    quote! {
        #![doc(
            html_logo_url="https://raw.githubusercontent.com/apache/datafusion/19fe44cf2f30cbdd63d4a4f52c74055163c6cc38/docs/logos/standalone_logo/logo_original.svg",
            html_favicon_url="https://raw.githubusercontent.com/apache/datafusion/19fe44cf2f30cbdd63d4a4f52c74055163c6cc38/docs/logos/standalone_logo/logo_original.svg"
        )]
        #![cfg_attr(docsrs, feature(doc_auto_cfg))]
    }
    .into()
}

This results in:

error: an inner attribute is not permitted in this context
  --> datafusion/core/src/lib.rs:19:1
   |
19 | datafusion_macros::doc_cfg!();
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: inner attributes, like `#![no_std]`, annotate the item enclosing them, and are usually found at the beginning of source files
   = note: outer attributes, like `#[test]`, annotate the item following them
   = note: this error originates in the macro `datafusion_macros::doc_cfg` (in Nightly builds, run with -Z macro-backtrace for more info)

For more information about this error, try `rustc --explain E0753`.

The other attempt was to use an attribute macro, but I don't think attaching this attribute to the lib.rs File item is supported.

Maybe we can use a normal macro_rules, but we would need another crate to export that to all crates.

[comphead]

Yes you totally right, we can use just macro_rules Ive double checked your original PR and I was mistakenly thought the doc attribute should have been applied on the object but in fact it is a crate level independent macros. so we do not need to use proc macros in this case

[Shreyaskr1409]

@comphead I would like to work on this issue. I will be looking into this.

[Shreyaskr1409]

take

[Shreyaskr1409]

Yes you totally right, we can use just macro_rules Ive double checked your original PR and I was mistakenly thought the doc attribute should have been applied on the object but in fact it is a crate level independent macros. so we do not need to use proc macros in this case

@comphead I tried using macro_rules but it did not work. i was getting the following error
proc-macros crate types currently cannot export any items other than functions tagged with #[proc_macro]

I even tried doing this in a separate crate, yet I was getting the same error.

I tried some workarounds with proc-macro but in those cases, it compiled correctly after a lot of refactoring, but the changes did not show up in the documentation.