Crate gh_docs_download

GitHub Documentation Downloader

A comprehensive library for discovering and downloading documentation files from GitHub repositories using git sparse checkout. This crate provides efficient git-based access to repository contents, with automatic discovery of documentation directories and intelligent file filtering.

Features

• Git Sparse Checkout: Efficient downloading using git sparse checkout for targeted paths
• Tree URL Support: Direct support for GitHub tree URLs (e.g., github.com/owner/repo/tree/branch/path)
• Documentation Detection: Smart identification of documentation files by extension and name
• Type Safety: Comprehensive use of semantic types to prevent category errors
• Error Handling: Detailed error types with actionable information
• Performance: Fast downloads without rate limiting concerns

Quick Start

use gh_docs_download::{
    downloader::{DownloadConfig, GitHubDocsDownloader},
    types::{RepoOwner, RepoName, RepoSpec},
};

// Create a repository specification
let owner = RepoOwner::new("rust-lang")?;
let name = RepoName::new("rust")?;
let repo = RepoSpec::new(owner, name);

// Configure the downloader with target path
let config = DownloadConfig {
    output_dir: "docs".to_string(),
    list_only: false,
    recursive: true,
    target_path: "src/doc".to_string(), // Specific documentation path
};

// Create downloader (git-only, no authentication needed)
let downloader = GitHubDocsDownloader::new(repo, config);

// Discover documentation directories
let docs_dirs = downloader.find_docs_directories()?;
println!("Found {} documentation directories", docs_dirs.len());

// Get all documentation files
let files = downloader.get_all_documentation_files(&docs_dirs)?;
println!("Found {} documentation files", files.len());

// Download the files
downloader.download_files(&files)?;

Architecture

The library is organized into several focused modules:

• error - Comprehensive error types with semantic meaning
• types - Domain types and newtypes for type safety
• downloader - Git-based downloading logic and configuration
• cli - Command-line interface and argument parsing

Error Handling

All operations return a Result type with detailed GitHubDocsError variants that provide actionable information about what went wrong.

use gh_docs_download::error::GitHubDocsError;

match some_operation().await {
    Err(GitHubDocsError::GitOperationFailed { command, stderr }) => {
        println!("Git command '{}' failed: {}", command, stderr);
    }
    Err(GitHubDocsError::RepositoryNotFound { owner, repo }) => {
        println!("Repository {}/{} not found or inaccessible", owner, repo);
    }
    Err(e) => {
        println!("Operation failed: {}", e);
    }
    Ok(result) => {
        // Handle success
    }
}

Re-exports

pub use error::GitHubDocsError;

pub use error::Result;

pub use types::DocsDirectory;

pub use types::DocumentationFile;

pub use types::DownloadUrl;

pub use types::FileName;

pub use types::FilePath;

pub use types::FileSizeBytes;

pub use types::RepoName;

pub use types::RepoOwner;

pub use types::RepoSpec;

Modules

cli

Command-line interface for the GitHub documentation downloader.

downloader

File downloader using git clone approach.

error

Error types for the GitHub documentation downloader.

types

Domain types for GitHub documentation handling.

Constants

VERSION

Library version information.