Add requirements.txt and update README for CodeMapper enhancements an…

…d rigorously reconciled our readme and function docstrings with each other and with the code itself.

README.md

@@ -16,34 +16,37 @@
     - [Options](#options)
   - [Output](#output)
   - [Use Cases](#use-cases)
-  - [TODO](#todo)
   - [Contributing](#contributing)
   - [License](#license)
   - [Acknowledgments](#acknowledgments)
   - [Version History](#version-history)
 
 ## Overview
 
-The CodeMapper is a powerful Python script that creates a comprehensive Markdown document representing the structure and contents of a given directory or GitHub repository. This tool is designed to provide a quick and thorough overview of codebases, making it invaluable for developers, AI systems, and analysts who need to quickly understand the layout and content of a project.
+CodeMapper is a powerful Python tool designed to generate comprehensive Markdown representations of codebases. It bridges the gap between human developers and AI systems by providing a clear, structured view of project architectures and their complete contents. Whether you're working with local directories or GitHub repositories, CodeMapper creates a single, navigable document that encapsulates the full structure and content of a project.
 
-See audio explainers for this project:
+This tool is invaluable for rapid codebase comprehension, whether you're a developer onboarding to a new project or an AI system analyzing code structure.
 
-- [podcasts](audio) Auto generated by Gemini (NotebookLLM)
+For audio explanations of this project, see:
+
+- [podcasts](audio) (Auto-generated by Gemini using NotebookLLM)
 
 ## Features
 
-- Generates a hierarchical table of contents based on file structure
-- Creates an accurate file tree representation of the directory structure
-- Produces code blocks for each file's contents with appropriate syntax highlighting
-- Respects `.gitignore` rules when processing files and directories
-- Excludes `.git` directories by default
-- Supports various file types with appropriate code fence highlighting
-- Handles file encoding detection for accurate content reading
-- Provides an option to include files normally ignored by `.gitignore`
-- Can clone and analyze GitHub repositories
-- Saves output in a '_codemaps' directory
-- Automatically acknowledges large and binary files without printing their contents
-- Displays file type and size information for large and binary files
+- **Dual-Purpose Output**: Generates content optimized for both human readers and AI analysis
+- **Intelligent Content Parsing**:
+  - Respects `.gitignore` rules
+  - Handles various file types appropriately
+- **Comprehensive Structure Representation**:
+  - Creates an accurate, hierarchical file tree
+  - Generates a smart table of contents for easy navigation
+- **Code-Aware Processing**:
+  - Applies appropriate syntax highlighting for different file types
+  - Intelligently handles large or binary files without bloating the output
+- **Flexible Input Handling**: Works with local directories and GitHub repositories
+- **Encoding Detection**: Ensures accurate content reading across various file encodings
+- **Customizable Ignore Rules**: Option to include files normally ignored by `.gitignore`
+- **Efficient Output Management**: Organizes generated documents in a '_codemaps' directory
 
 ## [Roadmap](./notes/todo.md)
 
@@ -57,7 +60,7 @@ See audio explainers for this project:
 
 ### From PyPI
 
-You can install CodeMapper directly from PyPI using pip:
+Install CodeMapper directly from PyPI using pip:
 
 ```sh
 pip install codemapper
@@ -68,56 +71,53 @@ pip install codemapper
 1. Clone this repository:
 
     ```sh
-    git clone https://github.com/yourusername/codemapper.git
+    git clone https://github.com/shaneholloman/codemapper.git
     ```
 
-2. Install the required dependencies:
+2. Navigate to the cloned directory and install the required dependencies:
 
     ```sh
-    pip install pathspec chardet
+    cd codemapper
+    pip install -r requirements.txt
     ```
 
 ## Usage
 
-Run the script from the command line, providing the path to the directory or GitHub repository URL you want to analyze:
+Run CodeMapper from the command line, providing the path to the directory or GitHub repository URL you want to analyze:
 
 ```sh
 codemapper <path_to_directory_or_github_url> [--include-ignored]
 ```
 
 ### Options
 
-- `<path_to_directory_or_github_url>`: The path to the directory or GitHub repository URL you want to analyze (required)
+- `<path_to_directory_or_github_url>`: The path to the directory or GitHub repository URL to analyze (required)
 - `--include-ignored`: Include files that are normally ignored by `.gitignore` (optional)
 
 ## Output
 
-The script generates a Markdown file named `<directory_name>codemap.md` in the '_codemaps' directory. This file contains:
+CodeMapper generates a Markdown file named `<directory_name>_codemap.md` in the '_codemaps' directory. This file contains:
 
-1. A table of contents for easy navigation
-2. A file tree representation of the directory structure
+1. A comprehensive table of contents for easy navigation
+2. An accurate file tree representation of the directory structure
 3. The contents of each file, formatted with appropriate syntax highlighting
 4. Information about large and binary files (type and size) without their contents
 
-Example use and output:
+Example usage and output:
 
-```python
+```sh
 codemapper https://github.com/shaneholloman/ansible-role-apache
 ```
 
-[Example output see here](_example/ansible-role-apache_codemap.md)
+[View example output here](_example/ansible-role-apache_codemap.md)
 
 ## Use Cases
 
-- Quickly understand the structure of new or unfamiliar projects
-- Generate documentation for your code-based Ai prompts
-- Facilitate code reviews by providing a comprehensive one page overview
-- Assist AI systems in analyzing and understanding codebases
-- Analyze GitHub repositories without needing to clone them manually
-
-## TODO
-
-[codemapper todo list is here](./notes/todo.md)
+- Rapidly understand the structure and content of new or unfamiliar projects
+- Generate comprehensive documentation for code-based AI prompts
+- Facilitate thorough code reviews by providing a complete one-page overview
+- Assist AI systems in analyzing and understanding complex codebases
+- Analyze GitHub repositories without manual cloning
 
 ## Contributing
 
@@ -129,12 +129,12 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Acknowledgments
 
-- Thanks to the `pathspec` and `chardet` libraries for making this tool possible.
+- Thanks to the `pathspec` and `chardet` libraries for enhancing CodeMapper's functionality.
 
 ## Version History
 
-[For full version history, see [changelog.md](changelog.md)]
+For a detailed version history, please refer to the [changelog.md](changelog.md).
 
 ---
 
-Don't forget to star this repository if you find it useful!
+If you find CodeMapper useful, don't forget to star this repository!

requirements.txt

@@ -0,0 +1,2 @@
+pathspec>=0.9.0
+chardet>=4.0.0