docs: add comprehensive API documentation for all crates - #37
Merged
Merged
Conversation
* chore: update Cargo.lock for workspace split Remove dependency entries for the old single-crate project and retain only entries for the three new workspace crates. This reflects the transition to a workspace layout. * refactor: convert to Cargo workspace with three crates Replace the single `librawssg` package with a workspace containing `librawssg_compiler`, `librawssg_handler`, and `librawssg_templates`. Add strict workspace-level lints for clippy and rustc. Remove all old dependencies and features. * refactor: remove src/config/loader.rs Delete the old YAML config loader implementation. Configuration handling will be reimplemented in the new workspace crates. * refactor: remove src/config/mod.rs Delete the old configuration module. Configuration functionality will be split across the new workspace crates. * refactor: remove src/error.rs Delete the old error type definitions. Error types will be redefined in the new workspace crates. * refactor: remove src/frontmatter.rs Delete the frontmatter parser. This logic will be moved to the appropriate new crate. * refactor: remove src/fs/mod.rs Delete the filesystem abstraction trait. Filesystem operations will be handled by the new crates. * refactor: remove src/fs/real.rs Delete the real filesystem implementation. It will be replaced by functionality in the new crates. * refactor: remove src/lib.rs Delete the old crate root. The library is now a workspace of multiple crates. * refactor: remove src/markdown.rs Delete the Markdown rendering trait and pulldown implementation. Markdown handling will be moved to the compiler crate. * refactor: remove src/serve/mod.rs Delete the development server module. Serving functionality will be reimplemented in the handler crate. * refactor: remove src/serve/watcher.rs Delete the file watcher module. Watch functionality will be part of the handler crate. * refactor: remove src/site/builders/mod.rs Delete the builders module declaration. Site building logic will be relocated. * refactor: remove src/site/builders/site.rs Delete the Site builder implementation. This core logic will be moved to the compiler crate. * refactor: remove src/site/builders/site_builder.rs Delete the SiteBuilder implementation. It will be reimplemented in the compiler crate. * refactor: remove src/site/context.rs Delete the context builder traits and Tera implementations. Context handling moves to the templates crate. * refactor: remove src/site/feed.rs Delete the RSS feed generation module. Feed generation will be part of the compiler crate. * refactor: remove src/site/mod.rs Delete the main site module that defined traits and handlers. These will be split across new crates. * refactor: remove src/site/page.rs Delete the page building logic. Page processing will be implemented in the compiler crate. * refactor: remove src/site/sitemap.rs Delete the sitemap generation module. This functionality moves to the compiler crate. * refactor: remove src/types.rs Delete the old configuration and page types. New type definitions will live in the appropriate workspace crates. * refactor: remove src/util.rs Delete utility functions including safe_path, slugify, and pattern matching. These will be reimplemented in the new crates. * feat: add librawssg_compiler crate manifest Create Cargo.toml for the new compiler crate, using workspace lints and no dependencies. * feat: add librawssg_compiler placeholder lib Add a placeholder library file with a simple add function and test to bootstrap the compiler crate. * feat: add librawssg_handler crate manifest Create Cargo.toml for the new handler crate, using workspace lints and no dependencies. * feat: add librawssg_handler placeholder lib Add a placeholder library file with a simple add function and test to bootstrap the handler crate. * feat: add librawssg_templates crate manifest Create Cargo.toml for the new templates crate, using workspace lints and no dependencies. * feat: add librawssg_templates placeholder lib Add a placeholder library file with a simple add function and test to bootstrap the templates crate.
* chore(lock): update lockfile for new workspace crates Add entries for librawssg_config, librawssg_error, librawssg_fs and adjust existing crate versions to 1.0.0. Include thiserror and its transitive dependencies. * feat(workspace): add config, error, fs crates to workspace Expand workspace members to include librawssg_config, librawssg_error, and librawssg_fs. Keep existing members. * chore(compiler): bump version to 1.0.0 and add metadata Set version to 1.0.0 and add description, license, repository, readme, keywords, and categories. * docs(compiler): add README for compiler crate Add a short description of the build pipeline orchestration role. * feat(config): add config crate manifest Create Cargo.toml for librawssg_config with description, license, repository, readme, keywords, and categories. Include workspace lints. * docs(config): add README for config crate Describe the purpose of the config crate. * feat(config): add placeholder library for config crate Add a simple placeholder lib.rs with add function and test to bootstrap the crate. * feat(error): add error crate manifest Create Cargo.toml for librawssg_error with thiserror dependency and metadata. Use workspace lints. * docs(error): add README for error crate Describe the unified error type and Result alias. * feat(error): define unified error enum and Result alias Add a non-exhaustive Error enum with variants for common SSG failures. Export Result type using thiserror. * test(error): add placeholder integration test file Create empty integration_tests.rs for future tests. * test(error): add placeholder property test file Create empty property_tests.rs for future tests. * test(error): add placeholder unit test file Create empty unit_tests.rs for future tests. * feat(fs): add fs crate manifest Create Cargo.toml for librawssg_fs with description, license, repository, readme, keywords, and categories. Use workspace lints. * docs(fs): add README for fs crate Describe the filesystem abstraction layer. * feat(fs): add placeholder library for fs crate Add a simple placeholder lib.rs with add function and test. * chore(handler): bump version to 1.0.0 and add metadata Set version to 1.0.0 and add description, license, repository, readme, keywords, and categories. * docs(handler): add README for handler crate Describe the content processing contracts. * chore(templates): bump version to 1.0.0 and add metadata Set version to 1.0.0 and add description, license, repository, readme, keywords, and categories. * docs(templates): add README for templates crate Describe the template rendering contracts.
* ci(workflows): improve CI pipeline and add build steps Update CI workflow with explicit job names and timeouts. Pin Rust toolchain to 1.96.0. Add build steps for debug and release, ensure formatting check runs in both jobs, and use workspace-wide clippy and test commands. * ci(workflows): remove obsolete docs deployment workflow Delete the GitHub Pages documentation deployment workflow. It is no longer needed since the workspace is being restructured and documentation deployment will be handled separately. * chore(gitignore): ignore generated PR body files Add pull_request_body.md to .gitignore to prevent temporary PR body files from being tracked accidentally. * refactor(makefile): expand build automation with per-crate targets Replace simple Makefile with comprehensive workspace targets. Add per-crate shortcuts, publish helpers, clippy flags variable, and improved help. This improves developer workflow across the new workspace. * test(error): add integration tests for error propagation Add tests verifying Io error conversion via From and Metadata error source accessibility using thiserror. * test(error): add property tests for error messages Add property tests ensuring Config, PathTraversal, and Render error messages preserve their input strings. * test(error): add unit tests for error enum Add comprehensive unit tests covering Display, source, From conversion, and Debug output for all error variants.
Change push and pull_request trigger branches from "master" to "*" so CI runs on every branch. This supports the new branching strategy and ensures early feedback for all feature and refactor branches.
* chore: update Cargo.lock for new dependencies Add entries for chrono, serde, tempfile, tracing, walkdir and their transitive dependencies. Update thiserror and syn versions to reflect new dependency graph. * feat(fs): add dependencies and dev-dependencies Add tracing and walkdir as runtime dependencies. Add tempfile as a dev dependency for tests. * feat(fs): define FileSystem trait and RealFs export Replace placeholder with a comprehensive FileSystem trait covering file, directory, symlink, and permission operations. Provide default implementations for path safety and fallback copy methods. Export RealFs. * feat(handler): add handler dependencies Add librawssg_error, librawssg_fs, chrono, and serde as dependencies. Chrono is configured without default features, enabling serde support. * feat(handler): expose Document, Metadata, and Processor Replace placeholder with module declarations for document, metadata, and processor. Re-export the public types. * feat(fs): implement RealFs for all FileSystem operations Add a concrete RealFs struct implementing the FileSystem trait. Use std::fs and walkdir to handle I/O, directory traversal, symlinks, permissions, atomic writes, and more. * test(fs): add comprehensive filesystem tests Add a test suite covering read/write, directories, copy, rename, atomic writes, symlinks, permissions, and path safety for the RealFs implementation. * feat(handler): define Document structure Add Document struct with metadata, body, URL, source path, depth, content type, list flag, and optional child documents. * feat(handler): define Metadata struct Add Metadata struct with title, description, author, repo URL, license, date, tags, and draft flag. Derives Serialize, Deserialize, and Default. * feat(handler): define Processor trait Add Processor trait with can_process and process methods. The process method accepts FileSystem and paths, returning Result<Option<Document>>.
* chore(handler): update lockfile for new dependencies Add serde_json and its transitive dependencies to Cargo.lock. This reflects the new serde_json dependency in librawssg_handler and keeps the lockfile in sync with Cargo.toml. * feat(handler): add serde_json dependency Add serde_json version 1.0.151 to librawssg_handler dependencies. This crate will be used for storing and manipulating extra metadata as JSON values. * feat(handler): enhance Document with validation and taxonomies Add `output_path`, `taxonomies`, and derive `PartialEq`. Make the struct non-exhaustive. Implement a constructor `new` with validation for URL, output_path, source_path, and depth. Add helper methods `relative_url`, `add_taxonomy`, and `depth`. * refactor(handler): allow multiple crate versions lint Add `#![allow(clippy::multiple_crate_versions)]` at crate root to suppress warnings about multiple versions of dependencies across the workspace. This keeps clippy output clean without affecting functionality. * feat(handler): extend Metadata with extra fields and methods Add `updated: Option<NaiveDate>` and `extra: HashMap<String, serde_json::Value>` fields. Make the struct non-exhaustive. Implement a constructor `new` that validates a non-empty title. Add helper methods `is_draft`, `insert_extra`, and `get_extra`. * feat(handler): add name and priority to Processor trait Extend the `Processor` trait with a required `name()` method and a default `priority()` method. These methods allow processors to be identified and ordered during content processing. * test(handler): add tests for Document Add comprehensive tests covering Document construction, validation errors, relative_url, add_taxonomy, depth, and default fields. * test(handler): add tests for Metadata Add tests for Metadata construction, validation, extra fields, draft flag, serialization, and deserialization from JSON. * test(handler): add tests for Processor trait Add tests using a mock Processor to verify name, priority, can_process, and process behavior. Includes a test for error propagation. * test(handler): add basic reexport availability test Add a test that ensures reexports of Metadata, Document, and Processor are available. This catches missing or broken public exports.
* chore(lock): update lockfile for config crate deps Add entries for serde_yaml and its dependencies, plus indexmap and unsafe-libyaml. Update existing entries to reflect new dependency graph. * feat(config): add dependencies for config crate Add librawssg_error, serde, serde_json, serde_yaml as dependencies and tempfile as dev-dependency. This enables config parsing, serialization, and testing. * feat(config): expose config modules and types Replace placeholder with module declarations for build, config, content_rule, nav, and site. Re-export public types and add crate-level lint allowance. * chore(handler): specify version for path dependencies Add version = "1.0.0" to librawssg_error and librawssg_fs path dependencies. This clarifies compatibility requirements and aligns with workspace versioning. * feat(config): define BuildConfig struct Add BuildConfig with content_dir, output_dir, templates_dir, static_dir and serde defaults. Implement Default, new, and derive traits for serialization. * feat(config): implement Config with validation and parsing Add Config struct with site, build, content_rules, extra. Provide methods for rule management, validation, YAML/JSON conversion. Validation checks site name, rules, patterns, and base_url. * feat(config): define ContentRule struct Add ContentRule with name, pattern, template, optional list fields, extra. Derive serde traits and provide a constructor. * feat(config): define NavItem struct Add NavItem with label, url, children and serde support. Provide a constructor and Default. * feat(config): define SiteConfig struct Add SiteConfig with nav, sidebar, site_name, description, language, base_url, author, repo_url, license, extra. Implement Default and a constructor. * test(config): add BuildConfig tests Add tests for default values, new equality, YAML roundtrip, and deserialization with defaults. * test(config): add Config tests Add comprehensive tests for Config construction, rule management, validation, YAML/JSON roundtrip, and error cases. * test(config): add ContentRule tests Add tests for constructor, default, and serialization roundtrip. * test(config): add NavItem tests Add tests for constructor, default, child addition, and serialization roundtrip. * test(config): add SiteConfig tests Add tests for constructor, default values, and serialization roundtrip.
* chore(lock): update lockfile for templates crate dependencies Add dependencies for tera and its transitive crates (chrono-tz, globwalk, pest, slug, etc.) to Cargo.lock. This reflects the new optional tera feature in librawssg_templates and keeps the lockfile in sync with Cargo.toml changes. * feat(templates): add tera feature and dependencies Add optional tera feature with default enabled. Add librawssg_error, walkdir, and tera dependencies. Add tempfile as dev-dependency. Update keywords to include tera. * feat(templates): expose renderer and tera modules Replace placeholder with module declarations for renderer and optional tera_renderer. Re-export public types and add crate-level lint allowance for multiple crate versions. * feat(templates): define RenderContext and Renderer traits Add RenderContext trait with as_any and as_mut_any methods. Add Renderer trait with render method returning Result<String>. * feat(templates): implement TeraRenderer Add TeraRenderer struct with methods for adding raw templates, loading from files/directories, enabling autoescape, and rendering. Implement Renderer and RenderContext for tera::Context. * test(templates): add TeraRenderer integration tests Add comprehensive tests for TeraRenderer including raw templates, loops, filters, conditions, file loading, recursion, autoescape, inheritance, macros, includes, and mutable access. * test(templates): add basic trait and reexport tests Add unit tests verifying Renderer and RenderContext traits can be mocked and reexports are available.
Add librawssg_config, librawssg_handler, librawssg_templates, and tempfile dependencies to compiler crate entry. This reflects new compiler Cargo.toml dependencies and keeps the lockfile synchronized.
Add librawssg_error, librawssg_fs, librawssg_config, librawssg_handler, and librawssg_templates as runtime dependencies. Add tempfile as dev-dependency. This prepares the compiler crate for building the pipeline.
Replace placeholder with module declarations for builder, context, generator, pattern, and pipeline. Re-export PipelineBuilder, ContextBuilder, Generator, Pipeline, and TeraContextBuilder under tera feature.
Add PipelineBuilder struct with config, content/output directories, filesystem, renderer, processors, context builder, and generators. Implement builder methods and `build` method that validates config and constructs a Pipeline.
Add ContextBuilder trait that builds a RenderContext from Config and Document. Implement TeraContextBuilder under the `tera` feature, populating a tera::Context with site and page fields.
Add Generator trait with a generate method that receives a Pipeline reference and returns Result. This allows post-processing generators to be plugged into the pipeline.
Implement match_pattern function and helper functions for matching path segments against glob patterns, including `**` and `*` wildcards. This is used for content type detection.
Add Pipeline struct with config, fs, renderer, processors, context builder, generators, content/output directories. Implement run method that generates to a temporary directory and atomically renames. Implement document processing, rendering, output writing, and static asset copying.
* chore(lock): update lockfile for compiler tera dependency
Add tera to librawssg_compiler dependencies in Cargo.lock. This reflects the new direct dependency and keeps the lockfile consistent with Cargo.toml.
* feat(compiler): add tera dependency
Add tera version 1.20.0 as a direct dependency to librawssg_compiler. This enables TeraContextBuilder without relying on optional feature and simplifies imports.
* refactor(builder): fix path comparisons and imports
Use `as_path() == Path::new("content")` instead of comparing PathBuf directly. Import `librawssg_handler::Processor` and add missing_debug_implementations attribute to PipelineBuilder. Improve code clarity and avoid type mismatches.
* refactor(context): remove feature gate from TeraContextBuilder
Derive Debug, Default, Clone, Copy for TeraContextBuilder and remove cfg(feature = "tera") attributes. Tera is now a required dependency, so the feature gate is no longer necessary.
* feat(compiler): update Generator trait signature
Add `output_base: &Path` parameter to `generate` method. This allows generators to write directly to the output directory during pipeline execution.
* refactor(compiler): remove feature gate and add test import
Remove `#[cfg(feature = "tera")]` from TeraContextBuilder re-export. Add `#[cfg(test)] use tempfile as _;` to suppress unused import warning in test builds.
* refactor(pattern): rewrite glob matching with safer indexing
Replace recursive slice indexing with match on pattern and segment options. Avoid potential panics by using get() and first(). Improve readability and maintainability of the pattern matching logic.
* refactor(pipeline): simplify list doc creation and static copy
Use Document::new and with_list_items to construct list documents instead of manual struct instantiation. Replace repeated path comparisons with let-else block for static directory copying. Add missing_debug_implementations attribute to Pipeline. Reverse content rule iteration to give later rules priority.
* feat(handler): add Serialize derive and with_list_items method
Derive Serialize for Document to support serialization in templates. Add a `with_list_items` builder method to set the list_items field fluently. This improves API ergonomics and enables future serialization.
* test(compiler): add comprehensive full compiler integration tests
Add full_compiler_test.rs covering pipeline generation of single pages, content type rules, list pages, static asset copying, generators, atomic replacement, empty content dir, skipped files, and error cases for missing renderer/context builder/invalid config. Uses MockRenderer and RawHtmlProcessor to test end-to-end behavior.
* chore: update .gitignore for demo output Add an additional `/dist` entry to ignore the generated demo site output. This prevents accidental commits of build artifacts. * chore: update lockfile for librawssg and demo crates Add entries for the new `librawssg` and `librawssg_demo` crates and their workspace dependencies. This keeps the lockfile synchronized with Cargo.toml. * feat(workspace): add librawssg and librawssg_demo to members Include the new `librawssg` placeholder crate and the `librawssg_demo` application in the workspace member list. This enables building and testing them alongside existing crates. * feat(librawssg): add placeholder crate manifest Create Cargo.toml for the top-level `librawssg` crate. This crate currently serves as a placeholder for future public API re-exports or convenience features. * feat(librawssg): add placeholder library Add a minimal lib.rs with a simple `add` function and a test. This bootstraps the top-level crate and allows workspace compilation. * feat(demo): add demo crate manifest Create Cargo.toml for `librawssg_demo` application. Declare dependencies on all librawssg workspace crates and set metadata. * feat(demo): add about page raw content Add a simple HTML about page that demonstrates how raw content files are processed by the demo pipeline. The content is static and will be rendered into a full page. * feat(demo): add index page raw content Add a welcome page with sample HTML. This file is processed by RawFileProcessor and demonstrates generation from a `.raw` source file. * feat(demo): add demo application entry point Implement main.rs with a custom RawFileProcessor and pipeline setup. Load Tera templates, configure content rules, and run the pipeline to generate a static site from `src/content`. * feat(demo): add static stylesheet Add a basic CSS file that styles the demo site. It is copied verbatim to the output directory by the pipeline's static asset handling. * feat(demo): add base Tera template Add a base HTML template that uses Tera placeholders for page title and content. It demonstrates how the compiler populates context values during rendering.
* chore(lock): update Cargo.lock for librawssg facade crate Update librawssg entry to version 1.0.0 and add dependencies on all workspace crates: compiler, config, error, fs, handler, templates. This reflects the new facade crate's Cargo.toml changes. * feat(librawssg): turn crate into facade with dependencies Bump version to 1.0.0 and add path dependencies to all internal workspace crates. Add package metadata including description, license, repository, readme, keywords, and categories. This enables the crate to re-export the entire library. * feat(librawssg): re-export all workspace crates and types Replace placeholder `add` function with module re-exports for config, fs, handler, templates, compiler, and error. Re-export common types like Config, Document, PipelineBuilder, TeraRenderer, and Error. Add `#![allow(clippy::multiple_crate_versions)]` to suppress workspace lint warnings. * docs(librawssg): add README for facade crate Add a short README describing the facade crate and listing the re-exported building blocks. This improves crate documentation and discoverability.
- Add root README.md with project overview, features, and usage examples - Create detailed API documentation for each workspace crate: - librawssg (facade) - librawssg_config - librawssg_fs - librawssg_handler - librawssg_templates - librawssg_compiler - librawssg_error - librawssg_demo - Include examples, validation rules, and testing details
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds thorough API documentation for every crate in the
librawssgworkspace, along with a rootREADME.mdthat provides an overview, quick start, and contribution guidelines.Changes
README.md: Added project description, features, repository structure, getting started instructions, and a minimal usage example.librawssg(facade): Documented all re-exported modules and types, including usage examples.librawssg_config: Full documentation forConfig,SiteConfig,BuildConfig,ContentRule, andNavItem— covering constructors, validation rules, serialization, and examples.librawssg_fs: Documented theFileSystemtrait andRealFsimplementation, including provided methods likesafe_joinandcanonicalize_or_join.librawssg_handler: DocumentedDocument,Metadata, and theProcessortrait with field tables and method descriptions.librawssg_templates: DocumentedRenderContext,Renderer, andTeraRenderer(including Tera-specific methods and autoescaping).librawssg_compiler: Detailed documentation forPipelineBuilder,Pipeline,ContextBuilder,Generator, and pattern matching.librawssg_error: Documented all error variants and theResultalias.librawssg_demo: Added a complete README explaining the demo application and how to run it.Scope
This PR only adds documentation. No functional code changes were made. The documentation is based on the current source code and test suite to ensure accuracy.
Checklist
cargo docbuilds without warnings (if applicable)