docs-kit 0.1.0

data/exe/docs-kit

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# docs-kit CLI. One command scaffolds a complete, deployable docs site:
+#
+#   docs-kit new my-docs
+#   docs-kit new my-docs --image mhenrixon/my-repo --service my-repo
+#
+# It runs `rails new` with the right minimal flags and applies docs-kit's
+# application template (lib/docs_kit/templates/new_site.rb), which adds the gem,
+# runs `docs_kit:install`, syncs icons, builds the CSS, and scaffolds Kamal +
+# the reusable deploy workflow.
+
+require "optparse"
+
+TEMPLATE = File.expand_path("../lib/docs_kit/templates/new_site.rb", __dir__)
+
+command = ARGV.shift
+
+unless command == "new"
+  warn <<~USAGE
+    docs-kit — scaffold a docs site.
+
+    Usage:
+      docs-kit new NAME [--image OWNER/REPO] [--service NAME] [--gem-source SRC]
+
+    Options:
+      --image     GHCR image (default mhenrixon/NAME) — use OWNER/REPO for the
+                  repo-linked package so GITHUB_TOKEN can push+pull it.
+      --service   Kamal service name (default NAME).
+      --gem-source  How to depend on docs-kit: 'released' (default),
+                  'path:PATH', or 'github:OWNER/REPO'.
+  USAGE
+  exit 1
+end
+
+name = ARGV.shift
+if name.nil? || name.start_with?("-")
+  warn "docs-kit new: NAME is required (e.g. docs-kit new my-docs)"
+  exit 1
+end
+
+opts = {}
+OptionParser.new do |o|
+  o.on("--image IMAGE") { |v| opts[:image] = v }
+  o.on("--service SERVICE") { |v| opts[:service] = v }
+  o.on("--gem-source SRC") { |v| opts[:gem_source] = v }
+end.parse!(ARGV)
+
+# Map --gem-source to the Gemfile fragment the template injects.
+gem_source =
+  case opts[:gem_source]
+  when nil, "released" then ""
+  when /\Apath:(.+)\z/ then %(path: "#{Regexp.last_match(1)}")
+  when /\Agithub:(.+)\z/ then %(github: "#{Regexp.last_match(1)}")
+  else opts[:gem_source]
+  end
+
+env = {
+  "DOCS_KIT_GEM_SOURCE" => gem_source,
+  "DOCS_KIT_IMAGE" => opts[:image] || "mhenrixon/#{name}",
+  "DOCS_KIT_SERVICE" => opts[:service] || name
+}
+
+# A lean docs app: propshaft + importmap + turbo + stimulus (the shell uses
+# javascript_importmap_tags and docs-kit's docs-nav Stimulus controller, so we do
+# NOT pass --minimal — that strips JS entirely). Skip the DB/mailer/cable/test
+# bits a docs site doesn't need.
+rails_new = [
+  "rails", "new", name,
+  "-a", "propshaft", "-j", "importmap",
+  "--skip-active-record", "--skip-action-mailer", "--skip-action-cable",
+  "--skip-action-text", "--skip-active-job", "--skip-active-storage",
+  "--skip-test", "--skip-system-test", "--skip-jbuilder", "--skip-kamal",
+  "--skip-solid", "--skip-ci", "--skip-docker", "--skip-bootsnap",
+  "-m", TEMPLATE
+]
+
+puts "→ #{rails_new.join(' ')}"
+exit system(env, *rails_new) ? 0 : 1

data/lib/docs-kit.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires the file matching the gem name ("docs-kit"); the real
+# entrypoint is the underscored docs_kit.rb (DocsKit module + Docs Phlex kit).
+require_relative "docs_kit"

data/lib/docs_kit/api_client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # One API-example language tab: a label, a Rouge lexer, a filename (a String or
+  # a `(request) -> String` proc), and a `template` — a `(DocsKit::ApiRequest) ->
+  # String` callable that renders the snippet. DocsUI::RequestExample turns each
+  # configured client into one DocsUI::Example tab.
+  #
+  #   DocsKit::ApiClient.new(
+  #     label: "cURL", lexer: :curl, filename: "request.sh",
+  #     template: ->(req) { "curl -X #{req.http_method} '#{req.url}'" }
+  #   )
+  #
+  # The gem ships four generic-HTTP defaults (DEFAULTS); a site overrides or
+  # extends them via DocsKit.configuration.api_clients (SDK-flavored snippets, a
+  # `cli` tab, ...).
+  ApiClient = Data.define(:label, :lexer, :filename, :template) do
+    def initialize(label:, lexer:, template:, filename: nil)
+      super
+    end
+
+    # The filename for this client's title bar: a static String, or the result of
+    # calling a proc filename with the request (so it can vary by verb/path).
+    def filename_for(request)
+      filename.respond_to?(:call) ? filename.call(request) : filename
+    end
+
+    # Render the snippet for this client from the request struct.
+    def render(request) = template.call(request)
+  end
+
+  # The four generic-HTTP clients every site starts from. Order is stable
+  # (curl → javascript → ruby → python) and preserved when a site merges its own.
+  ApiClient::DEFAULTS = {
+    curl: ApiClient.new(
+      label: "cURL", lexer: :curl, filename: "request.sh",
+      template: ApiTemplates.method(:curl)
+    ),
+    javascript: ApiClient.new(
+      label: "JavaScript", lexer: :javascript, filename: "request.js",
+      template: ApiTemplates.method(:javascript)
+    ),
+    ruby: ApiClient.new(
+      label: "Ruby", lexer: :ruby, filename: "request.rb",
+      template: ApiTemplates.method(:ruby)
+    ),
+    python: ApiClient.new(
+      label: "Python", lexer: :python, filename: "request.py",
+      template: ApiTemplates.method(:python)
+    )
+  }.freeze
+end

data/lib/docs_kit/api_request.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module DocsKit
+  # A single API request, declared once and handed to every client template so a
+  # snippet is authored one place, not per language. DocsUI::RequestExample builds
+  # one from its args (merging DocsKit.configuration.api_base_url + the auth header)
+  # and each DocsKit::ApiClient#template receives it.
+  #
+  #   req = DocsKit::ApiRequest.new(
+  #     method: :post, path: "/v1/things",
+  #     url: "https://api.example.com/v1/things",
+  #     body: { name: "Acme" }
+  #   )
+  #   req.http_method       # => "POST"
+  #   req.pretty_body_json  # => %({\n  "name": "Acme"\n})
+  #
+  # Templates stay one short heredoc each: they read #http_method, #url,
+  # #url_with_query, #headers, #body?, and #pretty_body_json.
+  ApiRequest = Data.define(:method, :path, :url, :query, :headers, :body) do
+    def initialize(method:, path:, url:, query: {}, headers: {}, body: nil)
+      super
+    end
+
+    # The upcased HTTP verb for display in a snippet ("POST", "GET", ...).
+    def http_method = method.to_s.upcase
+
+    # Whether the request carries a payload body (drives whether a template emits
+    # its payload lines at all).
+    def body? = !body.nil?
+
+    # The body as pretty-printed JSON with string keys (deep-stringified), or nil
+    # when there is no body. A String body is passed through unchanged.
+    def pretty_body_json
+      return nil unless body?
+      return body if body.is_a?(String)
+
+      JSON.pretty_generate(deep_stringify(body))
+    end
+
+    # A URL-encoded "?a=1&b=2" query string, or "" when there is no query.
+    def query_string
+      return "" if query.nil? || query.empty?
+
+      "?#{URI.encode_www_form(query)}"
+    end
+
+    # The URL with the query string appended (the copy-pasteable request target).
+    def url_with_query = "#{url}#{query_string}"
+
+    private
+
+    # Recursively stringify Hash/Array keys and symbol values so JSON output reads
+    # like a real API response (no Ruby :symbol / => syntax leaking through).
+    def deep_stringify(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s, deep_stringify(v)] }
+      when Array then value.map { |v| deep_stringify(v) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+  end
+end

data/lib/docs_kit/api_templates.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # The four generic-HTTP snippet templates the gem ships (curl, fetch, Net::HTTP,
+  # requests). Each is a `(DocsKit::ApiRequest) -> String` callable, referenced by
+  # DocsKit::ApiClient::DEFAULTS.
+  #
+  # The gem intentionally ships GENERIC HTTP snippets — it cannot know a site's
+  # SDK. A site swaps in SDK-flavored templates (or adds a `cli` client) by
+  # overriding c.api_clients; these are the fallback every site starts from.
+  #
+  # Every template guards its payload lines on request.body? so a body-less GET
+  # renders no dangling `-d`/`json=`/`request.body =` line.
+  module ApiTemplates
+    module_function
+
+    # curl -X METHOD 'url' [-H "Header: v"]... [-d '{json}']
+    def curl(request)
+      lines = ["curl -X #{request.http_method} '#{request.url_with_query}'"]
+      request.headers.each { |name, value| lines << %(  -H "#{name}: #{value}") }
+      lines << %(  -H "Content-Type: application/json") if request.body?
+      lines << "  -d '#{request.pretty_body_json}'" if request.body?
+      lines.join(" \\\n")
+    end
+
+    # A fetch() call with a headers object and an optional JSON body.
+    def javascript(request)
+      headers = { "Content-Type" => "application/json" }.merge(request.headers)
+      header_lines = headers.map { |k, v| %(    "#{k}": "#{v}") }.join(",\n")
+      body_line = request.body? ? %(\n  body: JSON.stringify(#{compact_json(request)}),) : ""
+
+      <<~JS.strip
+        const response = await fetch("#{request.url_with_query}", {
+          method: "#{request.http_method}",
+          headers: {
+        #{header_lines}
+          },#{body_line}
+        });
+        const data = await response.json();
+      JS
+    end
+
+    # A Net::HTTP snippet: build the request, set headers, optional JSON body, send.
+    def ruby(request)
+      header_lines = request.headers.map { |k, v| %(request["#{k}"] = "#{v}") }
+      body_line = request.body? ? %(request.body = #{request.pretty_body_json}.to_json) : nil
+
+      <<~RUBY.strip
+        require "net/http"
+        require "json"
+
+        uri = URI("#{request.url_with_query}")
+        request = Net::HTTP::#{request.http_method.capitalize}.new(uri)
+        request["Content-Type"] = "application/json"
+        #{[*header_lines, body_line].compact.join("\n")}
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.request(request)
+        end
+      RUBY
+    end
+
+    # A requests.<verb>(url, headers=..., json=...) call. Pretty JSON with
+    # double-quoted keys is valid Python dict syntax, so it drops straight into json=.
+    def python(request)
+      headers = { "Content-Type" => "application/json" }.merge(request.headers)
+      header_repr = headers.map { |k, v| %("#{k}": "#{v}") }.join(", ")
+      json_arg = request.body? ? ", json=#{request.pretty_body_json}" : ""
+
+      <<~PY.strip
+        import requests
+
+        response = requests.#{request.method.to_s.downcase}(
+            "#{request.url_with_query}",
+            headers={#{header_repr}}#{json_arg},
+        )
+        data = response.json()
+      PY
+    end
+
+    # --- helpers ------------------------------------------------------------
+
+    # The body as compact single-line JSON, for inlining in a JS literal.
+    def compact_json(request)
+      require "json"
+      json = request.pretty_body_json
+      JSON.generate(JSON.parse(json))
+    rescue JSON::ParserError
+      json
+    end
+  end
+end