gh_docs_download/
lib.rs

1//! # GitHub Documentation Downloader
2//!
3//! A comprehensive library for discovering and downloading documentation files
4//! from GitHub repositories using git sparse checkout. This crate provides
5//! efficient git-based access to repository contents, with automatic discovery of
6//! documentation directories and intelligent file filtering.
7//!
8//! ## Features
9//!
10//! - **Git Sparse Checkout**: Efficient downloading using git sparse checkout for targeted paths
11//! - **Tree URL Support**: Direct support for GitHub tree URLs (e.g., github.com/owner/repo/tree/branch/path)
12//! - **Documentation Detection**: Smart identification of documentation files by extension and name
13//! - **Type Safety**: Comprehensive use of semantic types to prevent category errors
14//! - **Error Handling**: Detailed error types with actionable information
15//! - **Performance**: Fast downloads without rate limiting concerns
16//!
17//! ## Quick Start
18//!
19//! ```rust,no_run
20//! use gh_docs_download::{
21//!     downloader::{DownloadConfig, GitHubDocsDownloader},
22//!     types::{RepoOwner, RepoName, RepoSpec},
23//! };
24//!
25//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
26//! // Create a repository specification
27//! let owner = RepoOwner::new("rust-lang")?;
28//! let name = RepoName::new("rust")?;
29//! let repo = RepoSpec::new(owner, name);
30//!
31//! // Configure the downloader with target path
32//! let config = DownloadConfig {
33//!     output_dir: "docs".to_string(),
34//!     list_only: false,
35//!     recursive: true,
36//!     target_path: "src/doc".to_string(), // Specific documentation path
37//! };
38//!
39//! // Create downloader (git-only, no authentication needed)
40//! let downloader = GitHubDocsDownloader::new(repo, config);
41//!
42//! // Discover documentation directories
43//! let docs_dirs = downloader.find_docs_directories()?;
44//! println!("Found {} documentation directories", docs_dirs.len());
45//!
46//! // Get all documentation files
47//! let files = downloader.get_all_documentation_files(&docs_dirs)?;
48//! println!("Found {} documentation files", files.len());
49//!
50//! // Download the files
51//! downloader.download_files(&files)?;
52//! # Ok(())
53//! # }
54//! ```
55//!
56//! ## Architecture
57//!
58//! The library is organized into several focused modules:
59//!
60//! - [`error`] - Comprehensive error types with semantic meaning
61//! - [`types`] - Domain types and newtypes for type safety
62//! - [`downloader`] - Git-based downloading logic and configuration
63//! - [`cli`] - Command-line interface and argument parsing
64//!
65//! ## Error Handling
66//!
67//! All operations return a [`Result`](error::Result) type with detailed
68//! [`GitHubDocsError`](error::GitHubDocsError) variants that provide
69//! actionable information about what went wrong.
70//!
71//! ```rust,no_run
72//! use gh_docs_download::error::GitHubDocsError;
73//!
74//! # async fn example() -> Result<(), GitHubDocsError> {
75//! match some_operation().await {
76//!     Err(GitHubDocsError::GitOperationFailed { command, stderr }) => {
77//!         println!("Git command '{}' failed: {}", command, stderr);
78//!     }
79//!     Err(GitHubDocsError::RepositoryNotFound { owner, repo }) => {
80//!         println!("Repository {}/{} not found or inaccessible", owner, repo);
81//!     }
82//!     Err(e) => {
83//!         println!("Operation failed: {}", e);
84//!     }
85//!     Ok(result) => {
86//!         // Handle success
87//!     }
88//! }
89//! # Ok(())
90//! # }
91//! # async fn some_operation() -> Result<(), GitHubDocsError> { Ok(()) }
92//! ```
93
94#![warn(missing_docs)]
95
96pub mod cli;
97pub mod downloader;
98pub mod error;
99pub mod types;
100
101// Re-export the most commonly used types for convenience
102pub use error::{GitHubDocsError, Result};
103pub use types::{
104    DocsDirectory, DocumentationFile, DownloadUrl, FileName, FilePath, FileSizeBytes, RepoName,
105    RepoOwner, RepoSpec,
106};
107
108/// Library version information.
109pub const VERSION: &str = env!("CARGO_PKG_VERSION");
gh_docs_download/lib.rs

gh_docs_download/
lib.rs
