From 60e688810daa431ef65212f9220ddccdf05b69fb Mon Sep 17 00:00:00 2001 From: despiegk Date: Wed, 9 Apr 2025 09:26:06 +0200 Subject: [PATCH] ... --- README.md | 235 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 234 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 84f3203..4a312b3 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,235 @@ -# doctree +# DocTree + +DocTree is a Rust library for managing collections of markdown documents with powerful include functionality. It provides a robust system for organizing, processing, and retrieving document collections with Redis-backed storage. + +## Overview + +DocTree scans directories for `.collection` files, which define document collections. Each collection contains markdown documents and other files (like images). The library provides functionality to: + +- Scan directories recursively to find collections +- Process includes between documents (allowing one document to include content from another) +- Convert markdown to HTML +- Store document metadata in Redis for efficient retrieval +- Provide a command-line interface for interacting with collections + +## Key Concepts + +### Collections + +A collection is a group of related documents and files. Collections are defined by a `.collection` file in a directory. The `.collection` file can be empty (in which case the directory name is used as the collection name) or it can contain TOML configuration: + +```toml +name = "my_collection" +# Other configuration options can be added in the future +``` + +### DocTree + +A DocTree is a manager for multiple collections. It provides methods for: + +- Adding collections +- Retrieving documents from collections +- Processing includes between documents +- Converting markdown to HTML +- Managing collection metadata in Redis + +### Includes + +One of the most powerful features of DocTree is the ability to include content from one document in another. This is done using the `!!include` directive: + +```markdown +# My Document + +This is my document. + +!!include another_collection:some_document.md + +More content here... +``` + +The include directive supports several formats: +- `!!include collection_name:page_name` - Include a page from a specific collection +- `!!include collection_name:'page name'` - Include a page with spaces from a specific collection +- `!!include page_name` - Include a page from the current collection +- `!!include name:'page name'` - Include a page with spaces from the current collection + +Includes can be nested, allowing for complex document structures. + +## Storage + +DocTree uses Redis as a backend storage system. Document metadata (like paths and names) is stored in Redis, making it efficient to retrieve documents without scanning the filesystem each time. + +The Redis keys are structured as: +- `collections:{collection_name}:{document_name}` - Stores the relative path to a document +- `collections:{collection_name}:path` - Stores the absolute path to the collection + +## Command-Line Interface + +DocTree comes with a command-line interface (CLI) that provides access to the library's functionality: + +``` +DocTree CLI 0.1.0 +A tool to manage document collections + +USAGE: + doctreecmd [SUBCOMMAND] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +SUBCOMMANDS: + delete-collection Delete a collection from Redis + get Get page content + html Get page content as HTML + info Show detailed information about collections + list List collections + reset Delete all collections from Redis + scan Scan a directory for .collection files and create collections +``` + +### Example Commands + +#### Scanning Collections + +```bash +doctreecmd scan /path/to/documents --doctree my_doctree +``` + +This command scans the specified directory for `.collection` files and creates collections in Redis. + +#### Listing Collections + +```bash +doctreecmd list --doctree my_doctree +``` + +This command lists all collections in the specified doctree. + +#### Getting Document Content + +```bash +doctreecmd get -c collection_name -p page_name --doctree my_doctree +``` + +This command retrieves the content of a document from a collection. + +#### Getting HTML Content + +```bash +doctreecmd get -c collection_name -p page_name -f html --doctree my_doctree +``` + +This command retrieves the HTML content of a document from a collection. + +#### Showing Collection Information + +```bash +doctreecmd info collection_name --doctree my_doctree +``` + +This command shows detailed information about a collection, including its documents and files. + +#### Deleting a Collection + +```bash +doctreecmd delete-collection collection_name --doctree my_doctree +``` + +This command deletes a collection from Redis. + +#### Resetting All Collections + +```bash +doctreecmd reset --doctree my_doctree +``` + +This command deletes all collections from Redis. + +## Implementation Details + +DocTree is implemented in Rust and uses several key dependencies: + +- `walkdir` for recursively walking directories +- `pulldown-cmark` for parsing and rendering markdown +- `toml` for parsing collection configuration files +- `redis` for interacting with Redis +- `clap` for the command-line interface + +The library is structured into several modules: + +- `doctree.rs` - Core DocTree functionality +- `collection.rs` - Collection management +- `include.rs` - Include processing +- `storage.rs` - Redis storage backend +- `utils.rs` - Utility functions +- `error.rs` - Error handling + +## Use Cases + +DocTree is particularly useful for: + +1. **Documentation Systems**: Manage and organize technical documentation with the ability to include common sections across multiple documents. + +2. **Content Management**: Create a flexible content management system where content can be modularized and reused. + +3. **Knowledge Bases**: Build knowledge bases with interconnected documents that can reference each other. + +4. **Static Site Generation**: Generate static websites from markdown documents with the ability to include common elements. + +## Getting Started + +### Prerequisites + +- Rust (latest stable version) +- Redis server running on localhost:6379 (or configure a different URL) + +### Building + +```bash +cargo build --release +``` + +### Running the CLI + +```bash +cargo run --bin doctreecmd -- [SUBCOMMAND] +``` + +### Using the Library + +Add doctree to your Cargo.toml: + +```toml +[dependencies] +doctree = { path = "path/to/doctree" } +``` + +Basic usage: + +```rust +use doctree::{DocTree, RedisStorage, Result, from_directory}; +use std::path::Path; + +fn main() -> Result<()> { + // Create a DocTree by scanning a directory + let doctree = from_directory(Path::new("path/to/documents"), Some("my_doctree"))?; + + // List collections + let collections = doctree.list_collections(); + for collection in collections { + println!("Collection: {}", collection); + } + + // Get a document with includes processed + let content = doctree.page_get(Some("collection_name"), "page_name")?; + println!("{}", content); + + // Get a document as HTML + let html = doctree.page_get_html(Some("collection_name"), "page_name")?; + println!("{}", html); + + Ok(()) +} +```