# dartdoc-advanced

This project provides tools for cleaning, repairing, and packaging HTML documentation generated by Dartdoc. It removes unnecessary stub files, fixes broken or invalid links, normalizes class sidebar paths, and produces a clean ZIP archive ready for distribution or publishing.

## The project includes:

* cleaning pipeline that processes Dartdoc output

* command-line interface for automation

* `a simple GUI for non-technical users

a modular internal architecture suitable for further development and integration with Dart or Pub.dev

## Features

* Removes small or empty HTML “stub” files based on configurable size thresholds
    
* Fixes duplicated folder prefixes inside class sidebars

* Disables dead, invalid, or trivial links (for example javascript: URLs)

* Normalizes links inside root index pages, library index pages, sidebars, and regular HTML pages

* Packages the cleaned documentation into a single ZIP file

* Includes a Tkinter GUI for easy use by non-technical users

* Provides a modular Python codebase organized by responsibility

## Project Structure

src/dartdoc_advanced/
- cleaner/
- core.py: main cleaning engine, tree copy, stub removal, HTML rewriting
- stubs.py: detection logic for stub files
- links.py: helpers for analyzing and classifying href values
- sidebar_fix.py: normalization and cleanup for class sidebar HTML files
- pipeline/
- runner.py: orchestrates the full process (cleaning, fixing, zipping)
- cli/
- cli.py: command-line interface entrypoint
-  gui/
- app.py: Tkinter desktop application

#### Pipeline Description

**The pipeline performs the following steps:**

1. Copies the original Dartdoc output directory into a temporary workspace.

2. Identifies and removes stub HTML files.

3. Processes remaining HTML files to fix or disable problematic links. 

4. Applies specialized rules for root index pages, library index pages, and class sidebars.

5. Produces a final ZIP file containing the cleaned documentation.

#### CLI Usage

**The command-line interface can be executed with:**

python -m dartdoc_advanced.cli.cli INPUT_DIR OUTPUT_ZIP --min-chars 350 --tiny-chars 150

**Arguments:**

* INPUT_DIR: path to the Dartdoc “doc/api” directory
* OUTPUT_ZIP: destination of the final ZIP file (with or without .zip extension)
* --min-chars: minimum number of characters required for sidebar/library HTML files
* --tiny-chars: minimum number of characters for all other HTML files

#### GUI Usage

**The GUI can be launched with:**

python -m dartdoc_advanced.gui.app

## The application allows users to:

* select the source Dartdoc directory
* choose where the ZIP file should be saved
* configure stub detection thresholds
* run the cleaning process in a background thread

## Developer Notes

The codebase is divided into small, purpose-specific modules, which makes it easy to test and extend.
The command-line entrypoint is stable and suitable for being called from other languages, such as Dart.
The project is prepared for packaging as a Python package and can easily expose an executable script.

## Link and Stub Logic Overview

**Stub rules:**

* “-library-sidebar.html” is always removed
* “-class-sidebar.html” and similar sidebar files are always kept
* other HTML files are removed if their textual content is below the configured thresholds

**Sidebar normalization:**

Paths with duplicated folders such as:

example/example/MyClass.html
are rewritten to:
example/MyClass.html

**Link disabling:**

* anchor links are kept
* external links are kept
* javascript: links are disabled
* links to missing or deleted HTML files are disabled

## License

MIT

## Contribution
Contributions and suggestions are welcome.
