...

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(())
+}
+```