search

webern / cargo-readme

Generate README.md from docstrings
Other
355 stars 57 forks source link

Using `cargo-readme` as a library for custom doc generation #109

Open nyurik opened 1 month ago

nyurik commented 1 month ago

I am implementing a proc-macro which allows users to generate Varnish caching proxy plugins. It would be good for users to automatically generate plugin documentation based on their code's doc comments, combined with the automatic comments by the proc-macro itself, and save that markdown file into the user's code tree.

Possible API:

// This is my proc-macro handler

use {proc_macro as pm, proc_macro2 as pm2};

#[proc_macro_attribute]
pub fn my_attribute(args: pm::TokenStream, input: pm::TokenStream) -> pm::TokenStream {
    // Parse token stream into some item
    let mut parsed_item_mod: ItemMod = syn::parse2::<ItemMod>(pm2::TokenStream::from(input)).unwrap();

    // modify parsed_item_mod doc attributes as needed

    // use readme's crate to generate some file
    // the item var might need to be wrapped into some syn::FileItem
    // Note that here I can control which code get documented and how
    cargo_readme::generate_md_file(parsed_item_mod, "../GENERATED.md");

    // ... finish additional processing and return generated stream to the compiler
}