docwright 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '089438eeadde6877f7ec2590b98c79d6698631099d3443223d77ca8f4cdbe581'
+  data.tar.gz: 2508d5a8a398a7c3df4650c2c32e9b09be1876a2bd23729b924c4914e6a34214
+SHA512:
+  metadata.gz: 5a4b6893d2308dc9cb0ba1d487413a5f9df48653f8dcf32aca1039e921701bee53fddbf16d0f78d2b48e67335fbeb52f07548d119e87189dac333c3acc032b81
+  data.tar.gz: e316d0cfd343876518a2315d619177cbd9d05db76b121d756bb2099385f5879cb5594a1072695bf2f919c34722fc8b4b3ae73fc428acba1b5247a1d11fda1f0e

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to DocWright will be documented here.
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Railtie integration — DocWright hooks into Rails boot automatically
+- `docwright:generate` — interactive wizard for guided documentation generation
+- Database documentation — auto-extracts tables, columns, and types
+- API documentation — auto-extracts routes and endpoints
+- Model documentation — auto-extracts associations and validations
+- Auth and permissions documentation — detects before/around/after action filters
+- Background jobs documentation — detects job classes, queues, priorities, and schedules
+- Services documentation — detects service classes and public methods
+- Concerns documentation — detects model and controller concerns
+- Manual templates — overview, setup, architecture, deployment, security, troubleshooting, business rules, changelog, readme
+- Feature-specific docs — declared in `.docwright.yml`
+- Smart merge markers — human-written content preserved across regenerations
+- `docwright:check` — audit task for missing files, placeholder content, empty notes
+- `docwright:search` — search across all documentation files

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Grace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# DocWright
+
+Auto-generate and maintain documentation for your Rails application.
+
+DocWright introspects your live Rails app to generate structured markdown
+documentation for your database schema, API routes, models, services,
+background jobs, and more. Human-written content is preserved across
+regenerations using smart merge markers.
+
+## Installation
+
+Add to your application's Gemfile:
+
+```ruby
+gem "docwright"
+```
+
+Then run:
+
+```bash
+bundle install
+bundle exec rake docwright:generate
+```
+
+## Usage
+
+### Generate documentation
+
+```bash
+rake docwright:generate
+```
+
+Runs the interactive wizard which:
+
+1. Scans your app and shows what will be generated
+2. Asks y/n to continue
+3. Generates auto files (database, API, models)
+4. Walks you through each new manual file with write/editor/skip options
+
+### Check documentation completeness
+
+```bash
+rake docwright:check
+```
+
+Audits your docs and reports:
+
+- Missing required files
+- Files with placeholder content only
+- Empty notes slots
+
+### Search documentation
+
+```bash
+rake docwright:search[your_term]
+```
+
+Searches across all generated markdown files.
+
+## Generated files
+
+### Auto-generated (always regenerated)
+
+- `docs/database.md` — tables, columns, types
+- `docs/api.md` — routes and endpoints
+- `docs/models.md` — associations and validations per model
+
+### Manual templates (written once, never overwritten)
+
+- `docs/overview.md`
+- `docs/setup.md`
+- `docs/architecture.md`
+- `docs/deployment.md`
+- `docs/security.md`
+- `docs/troubleshooting.md`
+- `docs/business_rules.md`
+- `docs/changelog.md`
+- `docs/readme.md`
+
+### Optional docs (declared in `.docwright.yml`)
+
+- `docs/auth_and_permissions.md`
+- `docs/background_jobs.md`
+- `docs/services.md`
+- `docs/concerns.md`
+- `docs/features/*.md`
+
+## Configuration
+
+Create `.docwright.yml` in your Rails app root:
+
+```yaml
+# Optional narrative docs
+optional_docs:
+  auth_and_permissions: true
+  background_jobs: true
+  services: true
+  concerns: true
+
+# Feature-specific docs
+features:
+  - name: qr_flow
+    description: QR code generation and scanning flow
+  - name: subscriptions
+    description: Billing and plan management
+```
+
+## How merge markers work
+
+Auto-generated content is wrapped in markers:
+
+<!-- DOCWRIGHT:AUTO -->
+
+auto content here — regenerated every time
+
+<!-- DOCWRIGHT:END -->
+
+Write your notes **outside** these markers — DocWright will never touch them.
+
+For per-model files, named markers are used:
+
+<!-- DOCWRIGHT:AUTO:Post -->
+
+auto content for Post
+
+<!-- DOCWRIGHT:END:Post -->
+
+Notes for Post
+
+your notes here — never overwritten
+
+## Development
+
+```bash
+git clone https://github.com/GraceHtet/docwright.git
+cd docwright
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/GraceHtet/docwright).
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/examples/.docwright.yml

@@ -0,0 +1,11 @@
+features:
+  - name: qr_flow
+    description: QR code generation and scanning flow
+  - name: subscriptions
+    description: Billing, plan management, and renewals
+
+optional_docs:
+  auth_and_permissions: true
+  background_jobs: true
+  services: true
+  concerns: true

data/examples/README.md

@@ -0,0 +1,28 @@
+# DocWright Examples
+
+Sample output generated by DocWright from a Rails app with:
+
+- 2 models (User, Post)
+- Nested routes (users, posts)
+- 1 concern (Publishable)
+
+## Files
+
+- `database.md` — auto-generated database schema documentation
+- `api.md` — auto-generated API routes documentation
+- `models.md` — auto-generated model documentation with merge markers
+- `.docwright.yml` — sample configuration file
+
+## Try it yourself
+
+Add DocWright to your Rails app's Gemfile:
+
+```ruby
+gem "docwright"
+```
+
+Then run:
+
+```bash
+rake docwright:generate
+```

data/examples/api.md

@@ -0,0 +1,20 @@
+<!-- DOCWRIGHT:AUTO -->
+# Api Documentation
+
+- **GET** /users/:user_id/posts(.:format) -> posts#index
+- **POST** /users/:user_id/posts(.:format) -> posts#create
+- **GET** /users/:user_id/posts/new(.:format) -> posts#new
+- **GET** /users/:user_id/posts/:id/edit(.:format) -> posts#edit
+- **GET** /users/:user_id/posts/:id(.:format) -> posts#show
+- **PATCH** /users/:user_id/posts/:id(.:format) -> posts#update
+- **PUT** /users/:user_id/posts/:id(.:format) -> posts#update
+- **DELETE** /users/:user_id/posts/:id(.:format) -> posts#destroy
+- **GET** /users(.:format) -> users#index
+- **POST** /users(.:format) -> users#create
+- **GET** /users/new(.:format) -> users#new
+- **GET** /users/:id/edit(.:format) -> users#edit
+- **GET** /users/:id(.:format) -> users#show
+- **PATCH** /users/:id(.:format) -> users#update
+- **PUT** /users/:id(.:format) -> users#update
+- **DELETE** /users/:id(.:format) -> users#destroy
+<!-- DOCWRIGHT:END -->

data/examples/concerns.md

@@ -0,0 +1,18 @@
+<!-- DOCWRIGHT:AUTO:Publishable -->
+#### Publishable
+- Type: Model Concern
+- Location: app/models/concerns/publishable.rb
+- Methods: publish, published?, unpublish
+- Included in: Post
+<!-- DOCWRIGHT:END:Publishable -->
+#### Notes for Publishable
+<!-- Describe what this concern adds and why it was extracted -->
+
+<!-- DOCWRIGHT:AUTO:_summary -->
+### Summary
+- Total concerns: 1
+- Model concerns: 1
+- Controller concerns: 0
+<!-- DOCWRIGHT:END:_summary -->
+### Notes for _summary
+<!-- Add your notes about _summary here -->

data/examples/database.md

@@ -0,0 +1,27 @@
+<!-- DOCWRIGHT:AUTO -->
+# Database Documentation
+
+## posts
+
+- **id** (integer)
+- **title** (string)
+- **body** (text)
+- **user_id** (integer)
+- **created_at** (datetime)
+- **updated_at** (datetime)
+- **published** (boolean)
+
+## users
+
+- **id** (integer)
+- **name** (string)
+- **email** (string)
+- **created_at** (datetime)
+- **updated_at** (datetime)
+
+<!-- DOCWRIGHT:END -->
+
+## My Notes
+
+These are my personal notes that should survive regeneration.
+created by Grace, and not auto replacable.

data/examples/models.md

@@ -0,0 +1,38 @@
+<!-- DOCWRIGHT:AUTO:Post -->
+## Post
+**Table:** posts
+
+### Associations
+- belongs_to :user
+
+### Validations
+- ActiveRecord::Validations::PresenceValidator on : user
+- ActiveRecord::Validations::PresenceValidator on : title
+- ActiveRecord::Validations::LengthValidator on : title
+- ActiveRecord::Validations::PresenceValidator on : body
+- ActiveRecord::Validations::LengthValidator on : body
+<!-- DOCWRIGHT:END:Post -->
+
+### Notes for Post
+
+<!-- Add your notes about Post here -->
+
+My note for post is here . They are blog post created by user
+
+<!-- DOCWRIGHT:AUTO:User -->
+## User
+**Table:** users
+
+### Associations
+- has_many :posts
+
+### Validations
+- ActiveRecord::Validations::PresenceValidator on : name
+- ActiveRecord::Validations::LengthValidator on : name
+<!-- DOCWRIGHT:END:User -->
+
+### Notes for User
+
+<!-- Add your notes about User here -->
+
+User is app user who can also create blog post.

data/lib/docwright/checker.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Docwright
+  class Checker
+    REQUIRED_FILES = %w[
+      docs/database.md
+      docs/api.md
+      docs/models.md
+      docs/overview.md
+      docs/business_rules.md
+      docs/setup.md
+      docs/architecture.md
+      docs/deployment.md
+      docs/security.md
+      docs/troubleshooting.md
+      docs/changelog.md
+      docs/readme.md
+    ].freeze
+
+    def run
+      puts "\nDocWright Check"
+      puts "===============\n\n"
+
+      missing = check_required_files
+      missing += check_optional_files
+      placeholders = check_placeholder_content
+      empty_notes = check_note_slots
+
+      print_report(missing, placeholders, empty_notes)
+
+      exit(1) if missing.any? || placeholders.any? || empty_notes.any?
+    end
+
+    private
+
+    def check_required_files
+      missing = []
+      REQUIRED_FILES.each do |file|
+        if File.exist?(file)
+          puts "✅ #{file}"
+        else
+          puts "❌ #{file} — missing"
+          missing << file
+        end
+      end
+
+      missing
+    end
+
+    def check_optional_files
+      missing = []
+      optional = load_optional_config
+      return missing if optional.empty?
+
+      optional_file_map = {
+        "auth_and_permissions" => "docs/auth_and_permissions.md",
+        "background_jobs" => "docs/background_jobs.md",
+        "services" => "docs/services.md",
+        "concerns" => "docs/concerns.md"
+      }
+
+      optional_file_map.each do |key, file|
+        next unless optional[key]
+
+        if File.exist?(file)
+          puts "✅ #{file}"
+        else
+          puts "❌ #{file} — missing (enabled in .docwright.yml)"
+          missing << file
+        end
+      end
+
+      missing
+    end
+
+    def load_optional_config
+      return {} unless File.exist?(".docwright.yml")
+
+      require "yaml"
+      config = YAML.load_file(".docwright.yml")
+      return {} unless config.is_a?(Hash)
+
+      config["optional_docs"] || {}
+    end
+
+    def check_placeholder_content
+      placeholders = []
+      all_files = REQUIRED_FILES.select { |f| File.exist?(f) }
+
+      all_files.each do |file|
+        content = File.read(file)
+        lines = content.lines.map(&:strip).reject(&:empty?)
+        real_lines = lines.reject { |l| l.start_with?("#", "<!--", "-->") }
+
+        if real_lines.empty?
+          puts "⚠  #{file} — placeholder content only"
+          placeholders << file
+        end
+      end
+
+      placeholders
+    end
+
+    def check_note_slots
+      empty_notes = []
+      md_files = Dir.glob("docs/**/*.md")
+
+      md_files.each do |file|
+        content = File.read(file)
+        lines = content.lines.map(&:chomp)
+
+        lines.each_with_index do |line, i|
+          next unless line.match?(/^#+\s+Notes for/)
+
+          following_lines = []
+          j = i + 1
+          while j < lines.size && !lines[j].match?(/^#+\s+Notes for/) && !lines[j].include?("DOCWRIGHT")
+            following_lines << lines[j]
+            j += 1
+          end
+
+          real_content = following_lines.map(&:strip).reject(&:empty?).reject { |l| l.start_with?("<!--", "-->") }
+
+          if real_content.empty?
+            puts "⚠  #{file} — empty notes slot: #{line.strip}"
+            empty_notes << "#{file}: #{line.strip}"
+          end
+        end
+      end
+
+      empty_notes
+    end
+
+    def print_report(missing, placeholders, empty_notes)
+      puts "\n==============="
+      puts "DocWright Check Summary"
+      puts "===============\n\n"
+
+      total_size = missing.size + placeholders.size + empty_notes.size
+
+      if total_size.zero?
+        puts "✅ All checks passed! Documentation looks complete."
+      else
+        puts "❌ Missing files: #{missing.size}"
+        puts "⚠  Placeholder content: #{placeholders.size}"
+        puts "⚠  Empty notes slots: #{empty_notes.size}"
+        puts "\nRun 'rake docwright:generate' to generate missing files."
+      end
+    end
+  end
+end

data/lib/docwright/extractors/api_extractor.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Docwright
+  module Extractors
+    class ApiExtractor
+      def generate
+        lines = ["# Api Documentation\n"]
+
+        routes = Rails.application.routes.routes
+        routes.each do |route|
+          next if route.name.to_s.start_with?("rails_")
+          next if route.verb.empty?
+          next if route.defaults[:controller].to_s.start_with?("rails/")
+
+          lines << "- **#{route.verb}** #{route.path.spec} -> #{route.defaults[:controller]}##{route.defaults[:action]}"
+        end
+
+        FileUtils.mkdir_p("docs")
+        Docwright::Merger.write("docs/api.md", lines.join("\n"))
+        puts "DocWright: wrote docs/api.md"
+      end
+    end
+  end
+end