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.