Block2Docs

Transforming DocBlocks into Documentation Workflows with AI

Documentation is the easy part—knowing what to document and how is the hard part. For every WordPress release, going through all Trac and GitHub tickets, labelling those that need documentation, and creating issues is a two-week job for a single person. A manual job that should never be done manually.

Block2Docs is a tool that bridges the gap between code and documentation by intelligent DocBlock parsing. It reads annotations from your code to identify what needs documentation, and routes everything to the appropriate output—changelog entries, GitHub issues, API references, field guides, and more.

Parser/Workflow Engine

The core parser scans PHP/JavaScript code, extracting DocBlocks and documentation, and needs to:

Generate API Docs: Create structured API documentation from inline comments.
Generate Changelogs: Extract version history from @since and @changelog tags.
Structure Field Guides: Automatically build release documentation frameworks.
Create GitHub Issues: Generate issues for items tagged @needs-docs, routed by doc type (dev note, end-user guide, how-to, tutorial).

Flexible Configuration

Config-driven: Use YAML/JSON for easy project customization.
Template System: Extensible templates; override defaults or create new ones.
Language Agnostic: Starts with PHP/JavaScript; architecture supports future languages.
CI/CD Ready: Integrates into existing development pipelines.

Target Audience

PHP Developers: Build the DocBlock parser for PHP, leveraging the PHPDocumentor libraries and handling WordPress-specific annotations such as hooks, actions, and filters.
JavaScript/TypeScript Developers: Implement the JS/TS parsing layer, handle JSDoc annotations, and build the CLI interface.
DevOps/CI Engineers: Create a GitHub Actions integration, design the issue-creation workflow, and build the template routing system.
Technical Writers: Define documentation type taxonomies, create issue templates, and ensure generated content follows documentation best practices.

Hackathon Goals

Develop a working CLI to parse PHP/JS annotations, extracting structured DocBlock data for documented and undocumented code.
Implement automated changelog generation using @since and @changelog tags, with fallback to git history for untagged changes.
Create a GitHub issue workflow for @needs-docs items that generates templated issues for documentation requirements (dev, user, guide).
Design a flexible configuration system for customizing parsing, output, and templates.
Produce a compelling demo on a real codebase (e.g., WordPress plugin), showcasing the full scanning-to-documentation/issue pipeline.

Results

What started as Block2Docs — a straightforward proposal to reduce the manual toil of open-source documentation work — evolved over three days into something with a name that demands to be said out loud: Doc2Me.

The project was born from a very real frustration. Milana Cap, a documentation contributor at WordPress.org, found herself spending so much time on repetitive, structural documentation tasks that she had almost no time left for the actual writing. Her goal was simple: build a tool that handles everything boring, so documentarians can focus on what matters.

The team was small, and alignment on scope proved challenging — small misunderstandings early on rippled into bigger friction by day two. But curious minds prevailed. A last-minute prototype by one team member demonstrated the core concept in action, and the final morning became a flurry of reordering slides, refining scope, and landing on that new name in a rather loud group chat moment.

The result is a tool that parses code, reads configuration files and git diffs, and uses @tags from code comments to automatically generate code references for PHP and JavaScript, changelogs, and GitHub issues. It also supports AI agent SKILLS for some tasks — though crucially, every feature works without AI too, keeping the tool fully open-source and free for anyone.

What makes Doc2Me stand out is its longevity guarantee: it solves its own project lead’s real, daily problem. It won’t be abandoned. It can’t be.