nym/documentation/autodoc/src/main.rs

use log::{debug, info};
use std::fs::File;
use std::io::{self, Write};
use std::process::{Command, Output};
use std::{fs, vec};

const WRITE_PATH: &str = "./autodoc-generated-markdown/";
const COMMAND_PATH: &str = "./autodoc-generated-markdown/commands/";

fn main() -> io::Result<()> {
    env_logger::init();

    // TODO if this balloons write automated way of grabbing commands from crates.
    let commands_with_subcommands = vec![
        (
            "../../target/release/nym-api",
            vec!["init", "run", "build-info"],
        ),
        (
            "../../target/release/nym-client",
            vec![
                "init",
                "run",
                "import-credential",
                "list-gateways",
                "switch-gateway",
                "build-info",
                "completions",
                "generate-fig-spec",
            ],
        ),
        (
            "../../target/release/nym-socks5-client",
            vec![
                "init",
                "run",
                "import-credential",
                "list-gateways",
                "add-gateway",
                "build-info",
                "completions",
                "generate-fig-spec",
            ],
        ),
        (
            "../../target/release/nym-node",
            vec![
                "build-info",
                "bonding-information",
                "node-details",
                "migrate",
                "run",
                "sign",
            ],
        ),
        (
            "../../target/release/nymvisor",
            vec![
                "init",
                "run",
                "build-info",
                "daemon-build-info",
                "add-upgrade",
                "config",
            ],
        ),
    ];

    let commands_with_subsubcommands = vec![(
        "../../target/release/nym-cli",
        vec![
            (
                "account",
                vec!["create", "balance", "pub-key", "send", "send-multiple"],
            ),
            ("signature", vec!["sign", "verify"]),
            (
                "ecash",
                vec![
                    "issue-ticket-book",
                    "recover-ticket-book",
                    "import-ticket-book",
                ],
            ),
            (
                "coconut",
                vec![
                    "generate-freepass",
                    "issue-credentials",
                    "recover-credentials",
                    "import-credential",
                ],
            ),
            ("block", vec!["get", "time", "current-height"]),
            (
                "cosmwasm",
                vec![
                    "upload",
                    "init",
                    "generate-init-message",
                    "migrate",
                    "execute",
                ],
            ),
            ("tx", vec!["get", "query"]),
            (
                "vesting-schedule",
                vec!["create", "query", "vested-balance", "withdraw-vested"],
            ),
            ("mixnet", vec!["query", "delegators", "operators"]),
            ("generate-fig", vec![""]),
        ],
    )];

    for (main_command, subcommands) in commands_with_subcommands {
        let last_word = get_last_word_from_filepath(main_command);
        debug!("now running {last_word:#?}");

        if !fs::metadata(WRITE_PATH)
            .map(|metadata| metadata.is_dir())
            .unwrap_or(false)
        {
            fs::create_dir_all(WRITE_PATH)?;
        }

        let mut file = File::create(format!("{}/{}-commands.md", WRITE_PATH, last_word.unwrap()))?;
        writeln!(
            file,
            "# {} Binary Commands (Autogenerated)",
            format!("`{}`", last_word.unwrap())
        )?;
        writeln!(
            file,
            "\nThese docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script."
        )?;
        let output = Command::new(main_command).arg("--help").output()?;
        write_output_to_file(&mut file, output)?;

        for subcommand in subcommands {
            // single file
            execute_command(&mut file, main_command, subcommand, None)?;
            // file per command
            execute_command_own_file(main_command, subcommand)?;
        }
    }

    // nym-cli has subsubcommands so needs its own loop
    for (main_command, subcommands) in &commands_with_subsubcommands {
        let last_word = get_last_word_from_filepath(main_command);
        debug!("now running {last_word:#?}");
        let mut file = File::create(format!("{}/{}-commands.md", WRITE_PATH, last_word.unwrap()))?;
        writeln!(
            file,
            "# {} Binary Commands (Autogenerated)",
            format!("`{}`", last_word.unwrap())
        )?;
        writeln!(
            file,
            "\nThese docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script."
        )?;
        let output = Command::new(main_command).arg("--help").output()?;

        write_output_to_file(&mut file, output)?;

        for (subcommand, subsubcommands) in subcommands {
            writeln!(file, "\n## `{}` ", subcommand)?;
            let output = Command::new(main_command)
                .arg(subcommand)
                .arg("--help")
                .output()?;
            if !output.stdout.is_empty() {
                write_output_to_file(&mut file, output)?;
            } else {
                debug!("empty stdout - nothing to write");
            }
            for subsubcommand in subsubcommands {
                execute_command(&mut file, main_command, subcommand, Some(subsubcommand))?;
            }
        }
    }
    Ok(())
}

fn get_last_word_from_filepath(filepath: &str) -> Option<&str> {
    let parts: Vec<&str> = filepath.split('/').collect();
    parts.last().copied()
}

fn execute_command_own_file(main_command: &str, subcommand: &str) -> io::Result<()> {
    // this check is basically checking for the rare commands (rn just one) that start a process with no params
    // perhaps if this list grows we could just add a timeout and shunt the running and writing
    // into a thread with a timeout or something but for right now its fine / thats overkill
    if get_last_word_from_filepath(main_command).unwrap() == "nym-node" && subcommand == "run"
        || get_last_word_from_filepath(main_command).unwrap() == "nym-api" && subcommand == "run"
        || get_last_word_from_filepath(main_command).unwrap() == "nymvisor" && subcommand == "run"
    {
        info!("SKIPPING {} {}", main_command, subcommand);
    } else {
        let last_word = get_last_word_from_filepath(main_command);
        let output = Command::new(main_command).arg(subcommand).output()?;
        if !output.stdout.is_empty() {
            info!("creating own file for {} {}", main_command, subcommand,);
            if !fs::metadata(WRITE_PATH)
                .map(|metadata| metadata.is_dir())
                .unwrap_or(false)
            {
                fs::create_dir_all(COMMAND_PATH)?;
            }
            let mut file = File::create(format!(
                "{}/{}-{}.md",
                COMMAND_PATH,
                last_word.unwrap(),
                subcommand
            ))?;
            write_output_to_file(&mut file, output)?;

            // execute help
            info!(
                "creating own file for {} {} --help",
                main_command, subcommand,
            );
            if !fs::metadata(COMMAND_PATH)
                .map(|metadata| metadata.is_dir())
                .unwrap_or(false)
            {
                fs::create_dir_all(COMMAND_PATH)?;
            }
            let mut help_file = File::create(format!(
                "{}/{}-{}-help.md",
                COMMAND_PATH,
                last_word.unwrap(),
                subcommand
            ))?;

            let output = Command::new(main_command)
                .arg(subcommand)
                .arg("--help")
                .output()?;
            if !output.stdout.is_empty() {
                write_output_to_file(&mut help_file, output)?;
            } else {
                debug!("empty stdout - nothing to write");
            }
        } else {
            info!(
                "creating own file for {} {} --help",
                main_command, subcommand,
            );
            if !fs::metadata(COMMAND_PATH)
                .map(|metadata| metadata.is_dir())
                .unwrap_or(false)
            {
                fs::create_dir_all(COMMAND_PATH)?;
            }
            let mut help_file = File::create(format!(
                "{}/{}-{}-help.md",
                COMMAND_PATH,
                last_word.unwrap(),
                subcommand
            ))?;

            let output = Command::new(main_command)
                .arg(subcommand)
                .arg("--help")
                .output()?;
            write_output_to_file(&mut help_file, output)?;
            debug!("empty stdout - nothing to write");
        }
    }
    Ok(())
}

fn execute_command(
    file: &mut File,
    main_command: &str,
    subcommand: &str,
    subsubcommand: Option<&str>,
) -> io::Result<()> {
    // checking for the nym-cli subsubcommands
    if subsubcommand.is_some() {
        writeln!(file, "\n### `{} {}`", subcommand, subsubcommand.unwrap())?;

        info!("executing {} {} --help ", main_command, subcommand);
        let output = Command::new(main_command)
            .arg(subcommand)
            .arg(subsubcommand.unwrap())
            .arg("--help")
            .output()?;
        if !output.stdout.is_empty() {
            write_output_to_file(file, output)?;
        } else {
            debug!("empty stdout - nothing to write");
        }
    // just subcommands
    } else {
        writeln!(file, "\n### `{}`", subcommand)?;

        // execute help
        let output = Command::new(main_command)
            .arg(subcommand)
            .arg("--help")
            .output()?;
        if !output.stdout.is_empty() {
            write_output_to_file(file, output)?;
        } else {
            debug!("empty stdout - nothing to write");
        }

        // then execute w/out help: the majority of functions will fail since you're not passing
        // required params but thats fine as we can just not render stderr into the final file.
        //
        // this check is basically checking for the rare commands (rn just one) that start a process with no params
        // perhaps if this list grows we could just add a timeout and shunt the running and writing
        // into a thread with a timeout or something but for right now its fine / thats overkill
        if get_last_word_from_filepath(main_command).unwrap() == "nym-node"
            || get_last_word_from_filepath(main_command).unwrap() == "nym-api"
            || get_last_word_from_filepath(main_command).unwrap() == "nymvisor"
                && subcommand == "run"
        {
            info!("SKIPPING {} {}", main_command, subcommand);
        } else {
            info!("executing {} {}", main_command, subcommand);
            let output = Command::new(main_command).arg(subcommand).output()?;
            if !output.stdout.is_empty() {
                writeln!(file, "Example output:")?;
                write_output_to_file(file, output)?;
            } else {
                debug!("empty stdout - nothing to write");
                if !&output.stderr.is_empty() {
                    debug!("stderr: {:#?}", String::from_utf8_lossy(&output.stderr));
                }
            }
        }
    }
    Ok(())
}

fn write_output_to_file(file: &mut File, output: Output) -> io::Result<()> {
    writeln!(file, "```sh")?;
    file.write_all(&output.stdout)?;
    writeln!(file, "```")?;

    if !&output.stderr.is_empty() {
        debug!("stderr: {:#?}", String::from_utf8_lossy(&output.stderr));
    }
    Ok(())
}