markdown-file-analyzer 0.1.0__tar.gz

markdown_file_analyzer-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: markdown-file-analyzer
+Version: 0.1.0
+Summary: A CLI tool to parse, analyze, and generate summary reports for Markdown files in directories.
+Author: Victor Okenwa
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# Markdown Directory Analyzer
+
+This project is a Python-based tool that analyzes a directory (and its subdirectories) of Markdown (`.md`) files and generates a comprehensive summary report. The goal is to provide insight into documentation quality and content metrics for codebases, technical blogs, knowledge bases, or any project using Markdown files.
+
+---
+
+## Features
+
+- **Recursive Scanning:** Analyzes all Markdown files within the specified root directory and subfolders.
+- **Per-File Metrics:** Reports for each file:
+  - File path
+  - Word count
+  - Header (e.g., `#`/`##`) count
+  - Code block count
+  - Estimated reading time (minutes, at 200 wpm)
+- **Aggregated Directory Metrics:** 
+  - Total number of Markdown files
+  - Combined word and code block counts
+  - Average reading time across files
+- **Generates a Markdown Summary:** Output includes a table breakdown of each file for easy reporting and sharing.
+- **CLI or Interactive Use:** Accepts directory as a command-line argument or prompts for user input.
+- **Saves Output:** Automatically saves analysis to `summary_report.md` in the current working directory.
+
+---
+
+## Getting Started
+
+### 1. **Install Requirements**
+
+Make sure you have Python 3.8+ installed.
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. **Usage**
+
+**From the command line:**
+```bash
+python main.py /path/to/your/markdown-directory
+```
+
+**Or run and enter directory interactively:**
+```bash
+python main.py
+# When prompted, type the target folder path (or press Enter for current directory)
+```
+
+After running, view or share your `summary_report.md`!
+
+---
+
+## Example Output
+
+```
+# Markdown Directory Analysis Summary
+
+- **Total Files Analyzed:** 5
+- **Total Word Count:** 12,500 words
+- **Total Code Blocks:** 16
+- **Avg Reading Time:** 10.32 minutes
+
+---
+
+### Individual File Breakdown
+| File Path           | Words | Headers | Code Blocks | Est. Read Time |
+| :---                | :---  | :---    | :---        | :---           |
+| docs/intro.md       | 1200  | 12      | 2           | 6.0 min        |
+| guide/howto.md      | 3000  | 25      | 5           | 15.0 min       |
+| ...                 | ...   | ...     | ...         | ...            |
+```
+
+---
+
+## Project Structure
+
+- `main.py` — Entry point, CLI, report formatting and saving.
+- `analyzer.py` — Analyzes the entire directory and aggregates results.
+- `parser.py` — Parses individual Markdown files and calculates metrics.
+- `models.py` — Data models (using Pydantic) for structured report and file metrics.
+- `requirements.txt` — List of Python dependencies.
+
+---
+
+## Extending / Customization
+
+- Add new metrics (e.g. link integrity, image stats) in `parser.py` and update models for richer reports.
+- Adjust reading speed estimation by changing the calculation logic.
+- Customize output format by editing the Markdown rendering in `main.py`.
+
+---
+
+## License
+
+MIT License
+
+---

markdown_file_analyzer-0.1.0/README.md

@@ -0,0 +1,97 @@
+# Markdown Directory Analyzer
+
+This project is a Python-based tool that analyzes a directory (and its subdirectories) of Markdown (`.md`) files and generates a comprehensive summary report. The goal is to provide insight into documentation quality and content metrics for codebases, technical blogs, knowledge bases, or any project using Markdown files.
+
+---
+
+## Features
+
+- **Recursive Scanning:** Analyzes all Markdown files within the specified root directory and subfolders.
+- **Per-File Metrics:** Reports for each file:
+  - File path
+  - Word count
+  - Header (e.g., `#`/`##`) count
+  - Code block count
+  - Estimated reading time (minutes, at 200 wpm)
+- **Aggregated Directory Metrics:** 
+  - Total number of Markdown files
+  - Combined word and code block counts
+  - Average reading time across files
+- **Generates a Markdown Summary:** Output includes a table breakdown of each file for easy reporting and sharing.
+- **CLI or Interactive Use:** Accepts directory as a command-line argument or prompts for user input.
+- **Saves Output:** Automatically saves analysis to `summary_report.md` in the current working directory.
+
+---
+
+## Getting Started
+
+### 1. **Install Requirements**
+
+Make sure you have Python 3.8+ installed.
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. **Usage**
+
+**From the command line:**
+```bash
+python main.py /path/to/your/markdown-directory
+```
+
+**Or run and enter directory interactively:**
+```bash
+python main.py
+# When prompted, type the target folder path (or press Enter for current directory)
+```
+
+After running, view or share your `summary_report.md`!
+
+---
+
+## Example Output
+
+```
+# Markdown Directory Analysis Summary
+
+- **Total Files Analyzed:** 5
+- **Total Word Count:** 12,500 words
+- **Total Code Blocks:** 16
+- **Avg Reading Time:** 10.32 minutes
+
+---
+
+### Individual File Breakdown
+| File Path           | Words | Headers | Code Blocks | Est. Read Time |
+| :---                | :---  | :---    | :---        | :---           |
+| docs/intro.md       | 1200  | 12      | 2           | 6.0 min        |
+| guide/howto.md      | 3000  | 25      | 5           | 15.0 min       |
+| ...                 | ...   | ...     | ...         | ...            |
+```
+
+---
+
+## Project Structure
+
+- `main.py` — Entry point, CLI, report formatting and saving.
+- `analyzer.py` — Analyzes the entire directory and aggregates results.
+- `parser.py` — Parses individual Markdown files and calculates metrics.
+- `models.py` — Data models (using Pydantic) for structured report and file metrics.
+- `requirements.txt` — List of Python dependencies.
+
+---
+
+## Extending / Customization
+
+- Add new metrics (e.g. link integrity, image stats) in `parser.py` and update models for richer reports.
+- Adjust reading speed estimation by changing the calculation logic.
+- Customize output format by editing the Markdown rendering in `main.py`.
+
+---
+
+## License
+
+MIT License
+
+---

markdown_file_analyzer-0.1.0/markdown_analyzer/analyzer.py

@@ -0,0 +1,35 @@
+# Directory wide scanning
+
+# Directory Scanner & Aggregator
+from pathlib import Path
+
+from markdown_analyzer.models import DirectoryReport, FileMetrics
+from markdown_analyzer.parser import analyze_file
+
+
+def analyze_directory(directory_path: str) -> DirectoryReport:
+    path = Path(directory_path)
+
+    mark_down_files = path.rglob("*.md") 
+    
+    metrics_list: list[FileMetrics] = [
+        analyze_file(str(file_path)) for file_path in mark_down_files
+    ]
+
+    total_files: int = len(metrics_list)
+    total_words: int = sum(file.word_count for file in metrics_list)
+    total_code_blocks: int = sum(file.code_block_count for file in metrics_list)
+
+    avg_reading_time= 0.0
+
+    if total_files > 0:
+        avg_reading_time: float = sum(file.reading_time_minutes for file in metrics_list) / total_files
+
+    return DirectoryReport(
+        total_files=total_files,
+        total_words=total_words,
+        total_code_blocks=total_code_blocks,
+        avg_reading_time=round(avg_reading_time, 2),
+        files=metrics_list
+    )
+

markdown_file_analyzer-0.1.0/markdown_analyzer/main.py

@@ -0,0 +1,95 @@
+import argparse
+from pathlib import Path
+from markdown_analyzer.analyzer import analyze_directory
+from markdown_analyzer.models import DirectoryReport
+
+# formats report into a beautiful Markdown string using multi-line f-strings
+def format_markdown_report(report: DirectoryReport) -> str:
+    # 1. Build table rows from report.files
+
+    table_rows = "\n".join(
+        f"| {f.file_path} | {f.word_count} | {f.header_count} | {f.code_block_count} | {f.reading_time_minutes} min |"
+        for f in report.files
+    )
+
+    # 2. Construct the full report string
+    report_md = f"""# Markdown Directory Analysis Summary
+
+- **Total Files Analyzed:** {report.total_files}
+- **Total Word Count:** {report.total_words:,} words
+- **Total Code Blocks:** {report.total_code_blocks}
+- **Avg Reading Time:** {report.avg_reading_time} minutes
+
+---
+
+### Individual File Breakdown
+| File Path | Words | Headers | Code Blocks | Est. Read Time |
+| :--- | :--- | :--- | :--- | :--- |
+{table_rows}
+"""
+    return report_md
+
+
+def main():
+    # 1. Initialize Parser with CLI metadata
+    parser = argparse.ArgumentParser(
+        prog="md-analyzer",
+        description="Parse and summarize Markdown file metrics across directories.",
+        epilog="Thanks for using md-analyzer!",
+    )
+
+    # 2. Define Positional & Optional Arguments
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Directory path to scan (default: current directory '.')",
+    )
+    parser.add_argument(
+        "-n",
+        "--no-save",
+        action="store_true",
+        help="Don't save report to file, just print to console",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        default="summary_report.md",
+        help="Output file name (default: 'summary_report.md')",
+    )
+
+    # 3. Parse arguments from CLI and store in args variable
+    args = parser.parse_args()
+
+
+    # 4. Resolve Path
+    target_path = Path(args.path)
+
+    if not target_path.exists():
+        print(f"❌ Error: Path '{args.path}' does not exist.")
+        return
+
+    print(f"\n🔍 Analyzing Markdown files in: {target_path.resolve()} ...\n")
+
+    # Run analysis & format output
+    analysis = analyze_directory(str(target_path))
+    formatted_report = format_markdown_report(analysis)
+
+    print(formatted_report)
+
+        # 5. Conditionally save report file based on --no-save flag    
+    if not args.no_save:
+        output_file = Path(args.output)
+        output_file.write_text(formatted_report, encoding="utf-8")
+        print(f"✅ Report saved to: {output_file.resolve()}")
+
+    else:
+        print("ℹ️ Skipping report file creation (--no-save passed).")
+
+
+if __name__ == "__main__":
+    main()
+
+
+

markdown_file_analyzer-0.1.0/markdown_analyzer/models.py

@@ -0,0 +1,19 @@
+# Pydantic Schemas
+from pydantic import BaseModel, Field
+
+#This model represents the analyzed statistics of a single Markdown file.
+class FileMetrics(BaseModel):
+    file_path: str
+    word_count: int = Field(default=0, ge=0)
+    reading_time_minutes: float = Field(default=0.0)
+    header_count: int = Field(default=0)
+    code_block_count: int = Field(default=0)
+    has_broken_links: bool = Field(default=False)
+
+# This model represents the aggregated summary of an entire folder filled with Markdown files.
+class DirectoryReport(BaseModel):
+    total_files: int
+    total_words: int
+    total_code_blocks: int
+    avg_reading_time: float
+    files: list[FileMetrics]

markdown_file_analyzer-0.1.0/markdown_analyzer/parser.py

@@ -0,0 +1,23 @@
+# Single file parsing Logic
+
+
+from markdown_analyzer.models import FileMetrics
+
+
+def analyze_file(file_path: str) -> FileMetrics:
+    with open(file_path, "r", encoding="utf-8") as file:
+        content = file.read()
+        word_count: int = len(content.split())
+        reading_time: float = word_count/200.0
+
+        lines = content.splitlines()
+        header_count: int = len([line for line in lines if line.strip().startswith("#")])
+        code_block_count: int = len([line for line in lines if line.strip().startswith("```")])//2
+
+        return FileMetrics(
+            file_path=file_path,
+            word_count=word_count,
+            reading_time_minutes=reading_time,
+            header_count=header_count,
+            code_block_count=code_block_count,
+        )

markdown_file_analyzer-0.1.0/markdown_file_analyzer.egg-info/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: markdown-file-analyzer
+Version: 0.1.0
+Summary: A CLI tool to parse, analyze, and generate summary reports for Markdown files in directories.
+Author: Victor Okenwa
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# Markdown Directory Analyzer
+
+This project is a Python-based tool that analyzes a directory (and its subdirectories) of Markdown (`.md`) files and generates a comprehensive summary report. The goal is to provide insight into documentation quality and content metrics for codebases, technical blogs, knowledge bases, or any project using Markdown files.
+
+---
+
+## Features
+
+- **Recursive Scanning:** Analyzes all Markdown files within the specified root directory and subfolders.
+- **Per-File Metrics:** Reports for each file:
+  - File path
+  - Word count
+  - Header (e.g., `#`/`##`) count
+  - Code block count
+  - Estimated reading time (minutes, at 200 wpm)
+- **Aggregated Directory Metrics:** 
+  - Total number of Markdown files
+  - Combined word and code block counts
+  - Average reading time across files
+- **Generates a Markdown Summary:** Output includes a table breakdown of each file for easy reporting and sharing.
+- **CLI or Interactive Use:** Accepts directory as a command-line argument or prompts for user input.
+- **Saves Output:** Automatically saves analysis to `summary_report.md` in the current working directory.
+
+---
+
+## Getting Started
+
+### 1. **Install Requirements**
+
+Make sure you have Python 3.8+ installed.
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. **Usage**
+
+**From the command line:**
+```bash
+python main.py /path/to/your/markdown-directory
+```
+
+**Or run and enter directory interactively:**
+```bash
+python main.py
+# When prompted, type the target folder path (or press Enter for current directory)
+```
+
+After running, view or share your `summary_report.md`!
+
+---
+
+## Example Output
+
+```
+# Markdown Directory Analysis Summary
+
+- **Total Files Analyzed:** 5
+- **Total Word Count:** 12,500 words
+- **Total Code Blocks:** 16
+- **Avg Reading Time:** 10.32 minutes
+
+---
+
+### Individual File Breakdown
+| File Path           | Words | Headers | Code Blocks | Est. Read Time |
+| :---                | :---  | :---    | :---        | :---           |
+| docs/intro.md       | 1200  | 12      | 2           | 6.0 min        |
+| guide/howto.md      | 3000  | 25      | 5           | 15.0 min       |
+| ...                 | ...   | ...     | ...         | ...            |
+```
+
+---
+
+## Project Structure
+
+- `main.py` — Entry point, CLI, report formatting and saving.
+- `analyzer.py` — Analyzes the entire directory and aggregates results.
+- `parser.py` — Parses individual Markdown files and calculates metrics.
+- `models.py` — Data models (using Pydantic) for structured report and file metrics.
+- `requirements.txt` — List of Python dependencies.
+
+---
+
+## Extending / Customization
+
+- Add new metrics (e.g. link integrity, image stats) in `parser.py` and update models for richer reports.
+- Adjust reading speed estimation by changing the calculation logic.
+- Customize output format by editing the Markdown rendering in `main.py`.
+
+---
+
+## License
+
+MIT License
+
+---

markdown_file_analyzer-0.1.0/markdown_file_analyzer.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+markdown_analyzer/__init__.py
+markdown_analyzer/analyzer.py
+markdown_analyzer/main.py
+markdown_analyzer/models.py
+markdown_analyzer/parser.py
+markdown_file_analyzer.egg-info/PKG-INFO
+markdown_file_analyzer.egg-info/SOURCES.txt
+markdown_file_analyzer.egg-info/dependency_links.txt
+markdown_file_analyzer.egg-info/entry_points.txt
+markdown_file_analyzer.egg-info/requires.txt
+markdown_file_analyzer.egg-info/top_level.txt

markdown_file_analyzer-0.1.0/markdown_file_analyzer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

markdown_file_analyzer-0.1.0/markdown_file_analyzer.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+md-analyzer = markdown_analyzer.main:main

markdown_file_analyzer-0.1.0/markdown_file_analyzer.egg-info/requires.txt

@@ -0,0 +1 @@
+pydantic>=2.0.0

markdown_file_analyzer-0.1.0/markdown_file_analyzer.egg-info/top_level.txt

@@ -0,0 +1 @@
+markdown_analyzer

markdown_file_analyzer-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "markdown-file-analyzer"        # Unique name on PyPI
+version = "0.1.0"
+description = "A CLI tool to parse, analyze, and generate summary reports for Markdown files in directories."
+readme = "README.md"
+authors = [
+    { name = "Victor Okenwa" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+    "pydantic>=2.0.0"
+]
+
+# This creates the terminal executable command!
+[project.scripts]
+md-analyzer = "markdown_analyzer.main:main"

markdown_file_analyzer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+