mkdocs_rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e5928dee130cd403c098bba987855573ac63d4e421eddaf21d8d1a1273124982
+  data.tar.gz: f437f4508e82f2e69ba322e9136b605d82c78fd0547faa6ad4ef005332011490
+SHA512:
+  metadata.gz: 27c4feb927d580d8017b10cc25c32718d2da3de32bfee404219bfdde25b53b8035496619ed581528a1c132d9aee5253556ede15cd0bb9f6985d41414fab58d7e
+  data.tar.gz: 7576bf72d80deae358a0c5d3a8fd3b12512d2af99760c42fff9493a3a79982cb17e6aeb2af9af1c3e090f046aae0312b8139929347351a9493610647d155c201

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-11-03
+
+### Added
+- Initial stable release
+- Rails generator for creating a full MkDocs documentation structure
+- Support for both **Material for MkDocs** and vanilla MkDocs themes
+- Automatic creation and management of a local Python virtual environment
+- Plugin auto-detection and installation from `docs/mkdocs.yml`
+- Custom plugin mappings via `docs/.mkdocs-packages`
+- `bin/docs` helper script with the following commands:
+  - `setup` – sets up the Python environment and installs dependencies
+  - `serve` – starts the MkDocs development server
+  - `publish` – builds and outputs static docs to `public/docs` for Rails serving
+  - `clean` – removes the published documentation files from `public/docs`
+
+[1.0.0]: https://github.com/yarbro/mkdocs_rails/releases/tag/v1.0.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 David Yarbro
+
+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,92 @@
+# MkDocs Rails
+
+Easy MkDocs setup for Rails development.
+
+## What It Does
+
+Adds [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) (or vanilla MkDocs) to your Rails app with one command. Perfect for internal documentation, API docs, and developer guides.
+
+## Installation
+
+Add to your Gemfile:
+```ruby
+gem "mkdocs_rails", group: :development
+```
+
+Then run:
+```bash
+bundle install
+rails generate mkdocs_rails:install
+```
+
+## Usage
+
+```bash
+# First-time setup (creates a local Python venv and installs packages)
+bin/docs setup
+
+# Start the MkDocs development server
+bin/docs serve
+# Visit http://localhost:8000
+
+# Build static docs directly into Rails public/docs
+bin/docs publish
+
+# Clean the public/docs directory
+bin/docs clean
+```
+
+The publish command outputs a production-ready static site to `public/docs`, automatically served by Rails at:
+
+```bash
+http://localhost:3000/docs/
+```
+
+The trailing slash (/) is required for the static docs to display correctly.
+
+## Features
+
+- Generator creates complete MkDocs project structure
+- Material for MkDocs theme by default (or use `--vanilla` for plain MkDocs)
+- Automatic Python virtual environment management
+- Auto-detects and installs plugins from `mkdocs.yml`
+- Simple `bin/docs` script for common tasks
+
+## Customization
+
+### Using Vanilla MkDocs
+```bash
+rails generate mkdocs_rails:install --vanilla
+```
+
+### Adding Plugins
+
+Edit `docs/mkdocs.yml`:
+```yaml
+plugins:
+  - search
+  - awesome-pages
+```
+
+Most plugins follow the convention `mkdocs-{name}-plugin`. For custom package names, create `docs/.mkdocs-packages`:
+```yaml
+plugins:
+  awesome-pages: mkdocs-awesome-pages-plugin
+  glightbox: mkdocs-glightbox
+```
+
+Then run `bin/docs setup` to install.
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am "Added some new feature"`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/generators/mkdocs_rails/install/install_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MkdocsRails
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    class_option :vanilla,
+                 type: :boolean,
+                 default: false,
+                 desc: "Use vanilla MkDocs instead of Material for MkDocs"
+
+    # TODO: Make this configurable
+    def create_docs_structure
+      empty_directory "docs"
+    end
+
+    def copy_mkdocs_config
+      if options[:vanilla]
+        template "mkdocs_vanilla.yml.tt", "mkdocs.yml"
+        template "docs/index_vanilla.md.tt", "docs/index.md"
+      else
+        template "mkdocs_material.yml.tt", "mkdocs.yml"
+        template "docs/index_material.md.tt", "docs/index.md"
+      end
+    end
+
+    def copy_package_mapping_template
+      template "mkdocs-packages.tt", "docs/.mkdocs-packages"
+    end
+
+    def copy_bin_script
+      template "bin/docs.tt", "bin/docs"
+      chmod "bin/docs", 0o755
+    end
+
+    def show_instructions
+      say "\n"
+      say "MkDocs Rails installed with #{theme_name}!", :green
+      say "\n"
+      say "Next steps:", :yellow
+      say "  1. Run setup: bin/docs setup"
+      say "  2. Start docs: bin/docs serve"
+      say "  3. Visit: http://localhost:8000"
+      say "\n"
+    end
+
+    private
+
+    def theme_name
+      options[:vanilla] ? "MkDocs" : "Material for MkDocs"
+    end
+
+    def app_name
+      Rails.application.class.module_parent_name
+    end
+  end
+end

data/lib/generators/mkdocs_rails/install/templates/bin/docs.tt

@@ -0,0 +1,178 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+DOCS_DIR = File.expand_path("../docs", __dir__)
+PROJECT_ROOT = File.expand_path("..", __dir__)
+PUBLIC_DOCS_DIR = File.join(PROJECT_ROOT, "public", "docs")
+VENV_DIR = File.join(PROJECT_ROOT, ".python-venv")
+MKDOCS_CONFIG = File.join(PROJECT_ROOT, "mkdocs.yml")
+GITIGNORE_PATH = File.join(PROJECT_ROOT, ".gitignore")
+PACKAGES_FILE = File.join(DOCS_DIR, ".mkdocs-packages")
+
+def mkdocs_command
+  venv_mkdocs = File.join(VENV_DIR, "bin", "mkdocs")
+  File.exist?(venv_mkdocs) ? venv_mkdocs : "mkdocs"
+end
+
+def pip_command
+  venv_pip = File.join(VENV_DIR, "bin", "pip")
+  File.exist?(venv_pip) ? venv_pip : "pip3"
+end
+
+def venv_exists?
+  Dir.exist?(VENV_DIR) && File.exist?(File.join(VENV_DIR, "bin", "python"))
+end
+
+def update_gitignore
+  return unless File.exist?(GITIGNORE_PATH)
+  return if File.read(GITIGNORE_PATH).include?(".python-venv")
+
+  File.open(GITIGNORE_PATH, "a") do |f|
+    f.puts "\n# MkDocs Python virtual environment"
+    f.puts ".python-venv/"
+  end
+
+  puts "Added .python-venv/ to .gitignore"
+end
+
+def load_custom_mappings
+  return {} unless File.exist?(PACKAGES_FILE)
+
+  config = YAML.load_file(PACKAGES_FILE)
+  config["plugins"] || {}
+rescue StandardError => e
+  puts "Warning: Could not parse .mkdocs-packages: #{e.message}"
+  {}
+end
+
+def load_mkdocs_config
+  return {} unless File.exist?(MKDOCS_CONFIG)
+
+  YAML.load_file(MKDOCS_CONFIG)
+rescue StandardError => e
+  puts "Warning: Could not parse mkdocs.yml: #{e.message}"
+  {}
+end
+
+def detect_theme_package(config)
+  theme_field = config["theme"]
+  theme_name =
+    if theme_field.is_a?(Hash)
+      theme_field["name"]
+    else
+      theme_field
+    end
+  theme_name == "material" ? "mkdocs-material" : "mkdocs"
+end
+
+def detect_plugin_packages(config, custom_mappings)
+  plugins = config["plugins"] || []
+
+  plugins.map do |plugin|
+    plugin_name = plugin.is_a?(Hash) ? plugin.keys.first : plugin
+    next if plugin_name == "search" # Built-in
+
+    custom_mappings[plugin_name] || "mkdocs-#{plugin_name}-plugin"
+  end.compact
+end
+
+def detect_required_packages
+  config = load_mkdocs_config
+  return ["mkdocs-material"] if config.empty?
+
+  theme_package = detect_theme_package(config)
+  custom_mappings = load_custom_mappings
+  plugin_packages = detect_plugin_packages(config, custom_mappings)
+
+  [theme_package] + plugin_packages
+end
+
+def package_installed?(package)
+  base_package = package.split("[").first
+  system("#{pip_command} show #{base_package} > /dev/null 2>&1")
+end
+
+def install_packages(packages)
+  return if packages.empty?
+
+  puts "Installing: #{packages.join(", ")}"
+  system("#{pip_command} install #{packages.join(" ")}") || exit(1)
+end
+
+def create_venv_if_missing
+  return if venv_exists?
+
+  puts "Creating Python virtual environment..."
+  system("python3 -m venv #{VENV_DIR}") || exit(1)
+  update_gitignore
+end
+
+def install_missing_packages
+  required = detect_required_packages
+  missing = required.reject { |pkg| package_installed?(pkg) }
+
+  if missing.empty?
+    puts "✓ All packages already installed!"
+  else
+    install_packages(missing)
+  end
+  required
+end
+
+def setup_mkdocs
+  puts "Setting up MkDocs..."
+
+  create_venv_if_missing
+  installed_packages = install_missing_packages
+
+  puts "\n✓ MkDocs setup complete!"
+  puts "\nInstalled packages:"
+  installed_packages.each { |pkg| puts "  - #{pkg}" }
+end
+
+def run_mkdocs(command)
+  Dir.chdir(PROJECT_ROOT) do
+    system("#{mkdocs_command} #{command}") || exit(1)
+  end
+end
+
+case ARGV[0]
+when "setup"
+  setup_mkdocs
+
+when "serve", "s"
+  # Auto-install any new plugins before serving
+  missing = detect_required_packages.reject { |pkg| package_installed?(pkg) }
+  install_packages(missing) unless missing.empty?
+
+  puts "Starting MkDocs server..."
+  run_mkdocs("serve")
+
+when "publish", "p"
+  FileUtils.mkdir_p(PUBLIC_DOCS_DIR)
+  puts "Publishing documentation to #{PUBLIC_DOCS_DIR}..."
+  run_mkdocs("build -d #{PUBLIC_DOCS_DIR}")
+
+when "clean"
+  puts "Cleaning build directory..."
+  FileUtils.rm_rf(File.join(PUBLIC_DOCS_DIR))
+  puts "Done!"
+
+else
+  puts <<~HELP
+    MkDocs Rails Helper
+
+    Usage:
+      bin/docs setup       Install MkDocs and plugins
+      bin/docs serve       Start the development server
+      bin/docs publish     Publish documentation to public directory
+      bin/docs clean       Remove public docs directory
+
+    Plugin Detection:
+      Plugins are auto-detected from mkdocs.yml and auto-installed.
+      Custom package mappings can be added to docs/.mkdocs-packages
+  HELP
+end

data/lib/generators/mkdocs_rails/install/templates/docs/index_material.md.tt

@@ -0,0 +1,48 @@
+# Welcome to <%= app_name %> Documentation
+
+Welcome! This is your documentation powered by Material for MkDocs.
+
+## Getting Started
+
+Edit this file at `docs/docs/index.md` to customize your documentation.
+
+## Features
+
+- 🎨 Beautiful Material Design theme
+- 🌓 Dark/light mode toggle
+- 🔍 Instant search
+- 📱 Mobile responsive
+- 💻 Syntax highlighting
+
+## Quick Links
+
+- [MkDocs Documentation](https://www.mkdocs.org/)
+- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
+
+## Adding More Pages
+
+Create new markdown files in `docs/docs/` and add them to the navigation in `docs/mkdocs.yml`.
+```yaml
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - API Reference: api.md
+```
+
+## Code Examples
+```ruby
+# Example Ruby code
+class User < ApplicationRecord
+  has_many :posts
+  validates :email, presence: true
+end
+```
+
+!!! tip "Pro Tip"
+    Use admonitions to highlight important information!
+
+!!! warning "Warning"
+    This is a warning admonition.
+
+!!! info "Information"
+    This is an info admonition.

data/lib/generators/mkdocs_rails/install/templates/docs/index_vanilla.md.tt

@@ -0,0 +1,30 @@
+# Welcome to <%= app_name %> Documentation
+
+Welcome! This is your documentation powered by MkDocs.
+
+## Getting Started
+
+Edit this file at `docs/docs/index.md` to customize your documentation.
+
+## Adding More Pages
+
+Create new markdown files in `docs/docs/` and add them to the navigation in `docs/mkdocs.yml`.
+```yaml
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - API Reference: api.md
+```
+
+## Code Examples
+```ruby
+# Example Ruby code
+class User < ApplicationRecord
+  has_many :posts
+  validates :email, presence: true
+end
+```
+
+## Resources
+
+- [MkDocs Documentation](https://www.mkdocs.org/)

data/lib/generators/mkdocs_rails/install/templates/mkdocs-packages.tt

@@ -0,0 +1,18 @@
+# Custom package mappings for MkDocs plugins
+# Only needed if a plugin doesn't follow the mkdocs-{name}-plugin convention
+#
+# Format:
+#   plugin-name: package-name
+#
+# Example:
+#   If your mkdocs.yml has:
+#     plugins:
+#       - awesome-pages
+#
+#   And the package name is mkdocs-awesome-pages-plugin, add:
+#     plugins:
+#       awesome-pages: mkdocs-awesome-pages-plugin
+#
+# After adding mappings here, run: bin/docs setup
+
+plugins: {}

data/lib/generators/mkdocs_rails/install/templates/mkdocs_material.yml.tt

@@ -0,0 +1,58 @@
+site_name: <%= app_name %> Documentation
+site_description: Documentation for <%= app_name %>
+
+# Uncomment to link to your repository
+# repo_name: username/repo
+# repo_url: https://github.com/username/repo
+# edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  # Uncomment to customize branding
+  # logo: assets/logo.png
+  # favicon: assets/favicon.png
+  palette:
+    # Light mode
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - md_in_html
+
+# Plugins are auto-installed by bin/docs setup
+# Most plugins follow the convention: mkdocs-{name}-plugin
+# For custom mappings, create docs/.mkdocs-packages
+plugins:
+  - search
+
+nav:
+  - Home: index.md

data/lib/generators/mkdocs_rails/install/templates/mkdocs_vanilla.yml.tt

@@ -0,0 +1,28 @@
+site_name: <%= app_name %> Documentation
+site_description: Documentation for <%= app_name %>
+
+# Uncomment to link to your repository
+# repo_name: username/repo
+# repo_url: https://github.com/username/repo
+# edit_uri: edit/main/docs/
+
+theme:
+  name: mkdocs
+
+markdown_extensions:
+  - admonition
+  - codehilite:
+      guess_lang: false
+  - toc:
+      permalink: true
+  - tables
+  - fenced_code
+
+# Plugins are auto-installed by bin/docs setup
+# Most plugins follow the convention: mkdocs-{name}-plugin
+# For custom mappings, create docs/.mkdocs-packages
+plugins:
+  - search
+
+nav:
+  - Home: index.md

data/lib/mkdocs_rails/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MkdocsRails
+  VERSION = "1.0.0"
+end

data/lib/mkdocs_rails.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "mkdocs_rails/version"
+
+module MkdocsRails
+  class Error < StandardError; end
+end

data/sig/mkdocs_rails.rbs

@@ -0,0 +1,4 @@
+module MkdocsRails
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: mkdocs_rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- David Yarbro
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Add Material for MkDocs documentation to your Rails app with generators
+  and helpful scripts
+email:
+- david@yarb.ro
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/mkdocs_rails/install/install_generator.rb
+- lib/generators/mkdocs_rails/install/templates/bin/docs.tt
+- lib/generators/mkdocs_rails/install/templates/docs/index_material.md.tt
+- lib/generators/mkdocs_rails/install/templates/docs/index_vanilla.md.tt
+- lib/generators/mkdocs_rails/install/templates/mkdocs-packages.tt
+- lib/generators/mkdocs_rails/install/templates/mkdocs_material.yml.tt
+- lib/generators/mkdocs_rails/install/templates/mkdocs_vanilla.yml.tt
+- lib/mkdocs_rails.rb
+- lib/mkdocs_rails/version.rb
+- sig/mkdocs_rails.rbs
+homepage: https://github.com/yarbro/mkdocs_rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yarbro/mkdocs_rails
+  source_code_uri: https://github.com/yarbro/mkdocs_rails
+  changelog_uri: https://github.com/yarbro/mkdocs_rails/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Easy MkDocs setup for Rails development
+test_files: []