Skip to content

Apache DataFusion SQL Query Engine

5.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements

//! Markdown renderer for DataFusion example documentation.
//!
//! This module takes parsed example metadata and generates the
//! `README.md` content for `datafusion-examples`, including group
//! sections and example tables.

use std::fmt::Write as _;
use std::path::PathBuf;

use datafusion::error::{DataFusionError, Result};

use crate::utils::example_metadata::discover::discover_example_groups;
use crate::utils::example_metadata::model::ExampleGroup;
use crate::utils::example_metadata::{Category, RepoLayout};

const STATIC_HEADER: &str = r#"<!--
SPDX-License-Identifier: Apache-2.0
SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
-->

# DataFusion Examples

This crate includes end to end, highly commented examples of how to use
various DataFusion APIs to help you get started.

## Prerequisites

Run `git submodule update --init` to init test files.

## Running Examples

To run an example, use the `cargo run` command, such as:

```bash
git clone https://github.com/apache/datafusion
cd datafusion
# Download test data
git submodule update --init

# Change to the examples directory
cd datafusion-examples/examples

# Run all examples in a group
cargo run --example <group> -- all

# Run a specific example within a group
cargo run --example <group> -- <subcommand>

# Run all examples in the `dataframe` group
cargo run --example dataframe -- all

# Run a single example from the `dataframe` group
# (apply the same pattern for any other group)
cargo run --example dataframe -- dataframe
```
"#;

/// Generates Markdown documentation for DataFusion examples.
///
/// If `group` is `None`, documentation is generated for all example groups.
/// If `group` is `Some`, only that group is rendered.
///
/// # Errors
///
/// Returns an error if:
/// - the requested group does not exist
/// - a `main.rs` file is missing
/// - documentation comments are malformed
pub fn generate_examples_readme(
    layout: &RepoLayout,
    group: Option<&str>,
) -> Result<String> {
    let examples_root = layout.examples_root();

    let mut out = String::new();
    out.push_str(STATIC_HEADER);

    let group_dirs: Vec<PathBuf> = match group {
        Some(name) => {
            let dir = examples_root.join(name);
            if !dir.is_dir() {
                return Err(DataFusionError::Execution(format!(
                    "Example group `{name}` does not exist"
                )));
            }
            vec![dir]
        }
        None => discover_example_groups(&examples_root)?,
    };

    for group_dir in group_dirs {
        let raw_name =
            group_dir
                .file_name()
                .and_then(|s| s.to_str())
                .ok_or_else(|| {
                    DataFusionError::Execution("Invalid example group dir".to_string())
                })?;

        let category = Category::for_group(raw_name);
        let group = ExampleGroup::from_dir(&group_dir, category)?;

        out.push_str(&group.render_markdown());
    }

    Ok(out)
}

impl ExampleGroup {
    /// Renders this example group as a Markdown section for the README.
    pub fn render_markdown(&self) -> String {
        let mut out = String::new();
        write!(out, "\n## {} Examples\n\n", self.name.title()).ok();
        write!(out, "### Group: `{}`\n\n", self.name.raw()).ok();
        write!(out, "#### Category: {}\n\n", self.category.name()).ok();
        out.push_str("| Subcommand | File Path | Description |\n");
        out.push_str("| --- | --- | --- |\n");

        for example in &self.examples {
            writeln!(
                out,
                "| {} | [`{}/{}`](examples/{}/{}) | {} |",
                example.subcommand,
                self.name.raw(),
                example.file,
                self.name.raw(),
                example.file,
                example.desc
            )
            .ok();
        }

        out
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    use crate::utils::example_metadata::test_utils::assert_exec_err_contains;

    use std::fs;

    use tempfile::TempDir;

    #[test]
    fn single_group_generation_works() {
        let tmp = TempDir::new().unwrap();
        // Fake repo root
        let layout = RepoLayout::from_root(tmp.path().to_path_buf());

        // Create: datafusion-examples/examples/builtin_functions
        let examples_dir = layout.example_group_dir("builtin_functions");
        fs::create_dir_all(&examples_dir).unwrap();

        fs::write(
            examples_dir.join("main.rs"),
            "//! - `x`\n//! (file: foo.rs, desc: test)",
        )
        .unwrap();

        let out = generate_examples_readme(&layout, Some("builtin_functions")).unwrap();
        assert!(out.contains("Builtin Functions"));
        assert!(out.contains("| x | [`builtin_functions/foo.rs`]"));
    }

    #[test]
    fn single_group_generation_fails_if_group_missing() {
        let tmp = TempDir::new().unwrap();
        let layout = RepoLayout::from_root(tmp.path().to_path_buf());
        let err = generate_examples_readme(&layout, Some("missing_group")).unwrap_err();
        assert_exec_err_contains(err, "Example group `missing_group` does not exist");
    }
}