elder_docs 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68f33b151c74c023dd2d59ca3d176bac9e165503197602c122555ef1de3027da
-  data.tar.gz: e4bd1f2f70f4f51cdb92c9ff7c74afffeef29384117474f0cdba3f5b9d76725c
+  metadata.gz: 6ec656c7eb8b5c1d06212d3004fbf785b6e4d1a4a5364d66dcf2f637447465c4
+  data.tar.gz: 691d4f247a2afa096ba57510fc515e926b44fff596fc9c56982e8682bdfe76ee
 SHA512:
-  metadata.gz: 44b63b766ce7a0a4d90939036d73ef172e939e804f36d59932f7bf71e3b646d63b11b5c23680df27f671908f73ecbf103db1d035dd32131eb87ae7fc0c079e5f
-  data.tar.gz: e03561a330840664aad9883a2fa042d08c805a49f67c16c685a2b847ed814bb9588d5fc36ce1292d8bc07daef7f0305f830641255dd03bb2b4e79a0d45a3b1db
+  metadata.gz: 1601af0b736fced56e45a3a44a3727d63114c34a28378c83ae4db4b49febd65e3756c03e221358c35847012760f0e0f6e5c2943c7ffebc8d8dcbb78a28ff8e96
+  data.tar.gz: dd5209f2fbbed2e74a4a75cc10e2b43920640ad975e0d38d0b492714a747526e3624e4918cea5ba3b8016e615cf2428f36080a7f5ad320bb9ad409c968bf9c0a

data/README.md

@@ -5,10 +5,11 @@ Interactive API documentation for Rails. Convert your OpenAPI spec into a beauti
 ## Features
 
 - 🚀 **Interactive API Explorer** - Test endpoints directly from docs
-- 🎨 **Customizable UI** - Web-based configurator at `/docs/ui`
+- 🎨 **Customizable UI** - Configure via `elderdocs.yml`
 - 📖 **Guides & Articles** - Add custom documentation
 - 🔐 **Multiple Auth Types** - Bearer, API Key, Basic, OAuth2
-- ⚡ **Zero Config** - Works out of the box
+- ⚡ **Zero Compilation** - Edit JSON files, changes appear instantly!
+- 📋 **Copy cURL** - One-click copy of API requests
 
 ## Installation
 
@@ -65,13 +66,16 @@ Create `articles.json`:
 ]
 ```
 
-### 3. Generate docs
+### 3. Build frontend (one-time setup)
 
 ```bash
 bundle exec elderdocs deploy
 ```
 
-This builds the SPA into `public/elderdocs` (configurable via `output_path`) so the assets live alongside your application code.
+This builds the frontend SPA into `public/elderdocs` (configurable via `output_path`).
+
+**Note:** This is a one-time build. After this, you can edit `definitions.json` and `articles.json` - changes appear instantly without rebuilding!
+
 ### 4. Mount in routes
 
 ```ruby
@@ -83,11 +87,15 @@ mount ElderDocs::Engine, at: '/docs'
 
 Open `http://localhost:3000/docs` 🎉
 
-## Customize UI
+## Dynamic Updates
+
+**No compilation needed!** After the initial build:
 
-Visit `/docs/ui` to customize fonts, colors, and styling with a visual editor.
+- ✏️ Edit `definitions.json` → Changes appear immediately
+- ✏️ Edit `articles.json` → Changes appear immediately  
+- ✏️ Edit `elderdocs.yml` → Restart Rails server to see UI changes
 
-**Default password:** `admin` (or set `admin_password` in `elderdocs.yml`)
+The frontend fetches data dynamically from your JSON files at runtime.
 
 ## Configuration
 
@@ -111,7 +119,7 @@ auth_types:
   - basic
   - oauth2
 
-# UI customization (or use /docs/ui)
+# UI customization
 ui:
   font_heading: 'Syne'
   font_body: 'IBM Plex Sans'
@@ -122,8 +130,9 @@ ui:
     surface: '#ffffff'
   corner_radius: '0px'
 
-# Admin password for /docs/ui
-admin_password: your-secure-password
+# Custom file paths (optional, defaults to definitions.json and articles.json)
+definitions_file: definitions.json
+articles_file: articles.json
 
 # Where to write generated assets (relative paths are resolved from Rails.root)
 output_path: ./public/elderdocs

data/elderdocs.yml.example

@@ -8,9 +8,9 @@ mount_path: /docs
 # Output directory for generated assets (relative to your Rails root)
 output_path: ./public/elderdocs
 
-# Admin password for UI configuration page (/docs/ui)
-# Default: 'admin' (or set via ELDERDOCS_ADMIN_PASSWORD environment variable)
-# admin_password: your-secure-password-here
+# Custom file paths (optional, defaults to definitions.json and articles.json in Rails root)
+# definitions_file: definitions.json
+# articles_file: articles.json
 
 # Default API server URL (overrides OpenAPI servers if set)
 # Leave empty to use the first server from your OpenAPI spec

data/frontend/src/App.jsx

@@ -81,49 +81,50 @@ function App() {
   }, [])
 
   useEffect(() => {
-    const initializeData = (payload) => {
-      setData(payload)
-      setLoading(false)
-      
-      if (payload.openapi?.paths) {
-        const firstPath = Object.keys(payload.openapi.paths)[0]
-        const firstMethod = Object.keys(payload.openapi.paths[firstPath])[0]
-        setSelectedItem({ type: 'endpoint', path: firstPath, method: firstMethod })
-      } else if (payload.articles?.length > 0) {
-        setSelectedItem({ type: 'article', id: payload.articles[0].id })
-      }
-    }
-    
-    const tryInitialize = () => {
-      if (window.ElderDocsData) {
-        initializeData(window.ElderDocsData)
-        return true
-      }
-      return false
-    }
-    
-    if (!tryInitialize()) {
-      const handleDataLoaded = () => {
-        if (window.ElderDocsData) {
-          initializeData(window.ElderDocsData)
+    const loadData = async () => {
+      try {
+        // Fetch all data in parallel
+        const [definitionsRes, articlesRes, configRes] = await Promise.all([
+          fetch('/docs/api/definitions'),
+          fetch('/docs/api/articles'),
+          fetch('/docs/api/config')
+        ])
+        
+        if (!definitionsRes.ok) {
+          throw new Error(`Failed to load definitions: ${definitionsRes.statusText}`)
         }
-      }
-      
-      window.addEventListener('elderdocs:data_loaded', handleDataLoaded)
-      
-      // Fallback timeout so we don't wait forever
-      const timeoutId = setTimeout(() => {
-        if (!window.ElderDocsData) {
-          console.error('ElderDocsData not found. Make sure data.js is loaded.')
-          setLoading(false)
+        
+        const openapi = await definitionsRes.json()
+        const articles = articlesRes.ok ? await articlesRes.json() : []
+        const config = configRes.ok ? await configRes.json() : {}
+        
+        const payload = {
+          openapi,
+          articles,
+          api_server: config.api_server || '',
+          api_servers: config.api_servers || [],
+          auth_types: config.auth_types || ['bearer', 'api_key', 'basic', 'oauth2'],
+          ui_config: config.ui_config || {},
+          generated_at: new Date().toISOString()
         }
-      }, 5000)
-      
-      return () => {
-        window.removeEventListener('elderdocs:data_loaded', handleDataLoaded)
-        clearTimeout(timeoutId)
+        
+        setData(payload)
+        setLoading(false)
+        
+        if (payload.openapi?.paths) {
+          const firstPath = Object.keys(payload.openapi.paths)[0]
+          const firstMethod = Object.keys(payload.openapi.paths[firstPath])[0]
+          setSelectedItem({ type: 'endpoint', path: firstPath, method: firstMethod })
+        } else if (payload.articles?.length > 0) {
+          setSelectedItem({ type: 'article', id: payload.articles[0].id })
+        }
+      } catch (error) {
+        console.error('Failed to load ElderDocs data:', error)
+        setLoading(false)
       }
     }
+    
+    loadData()
   }, [])
 
   if (loading) {

data/frontend/src/components/ApiExplorer.jsx

@@ -11,6 +11,8 @@ const ApiExplorer = ({ data, selectedItem }) => {
   const [loading, setLoading] = useState(false)
   const [response, setResponse] = useState(null)
   const [isOpen, setIsOpen] = useState(true)
+  const [copied, setCopied] = useState(false)
+  const [showCurlPreview, setShowCurlPreview] = useState(false)
   
   const authTypes = data?.auth_types || ['bearer', 'api_key', 'basic', 'oauth2']
   const currentAuthType = authConfig?.type || 'bearer'
@@ -81,6 +83,85 @@ const ApiExplorer = ({ data, selectedItem }) => {
     return url
   }
 
+  const generateCurl = () => {
+    const url = buildUrl()
+    const method = selectedMethod.toUpperCase()
+    const curlParts = [`curl -X ${method}`]
+    
+    // Add URL
+    curlParts.push(`"${url}"`)
+    
+    // Add headers
+    const requestHeaders = {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+    
+    // Apply authentication based on type
+    if (authConfig?.value) {
+      switch (authConfig.type) {
+        case 'bearer':
+          requestHeaders['Authorization'] = `Bearer ${authConfig.value}`
+          break
+        case 'api_key':
+          requestHeaders['X-API-Key'] = authConfig.value
+          break
+        case 'basic':
+          requestHeaders['Authorization'] = `Basic ${btoa(authConfig.value)}`
+          break
+        case 'oauth2':
+          requestHeaders['Authorization'] = `Bearer ${authConfig.value}`
+          break
+      }
+    }
+    
+    // Add all headers to curl command
+    Object.entries(requestHeaders).forEach(([key, value]) => {
+      curlParts.push(`-H "${key}: ${value}"`)
+    })
+    
+    // Add request body if present
+    if (['POST', 'PUT', 'PATCH'].includes(method) && body) {
+      try {
+        // Validate and format JSON
+        const jsonBody = JSON.parse(body)
+        const formattedBody = JSON.stringify(jsonBody)
+        curlParts.push(`-d '${formattedBody}'`)
+      } catch {
+        // If not valid JSON, add as-is
+        curlParts.push(`-d '${body}'`)
+      }
+    }
+    
+    return curlParts.join(' \\\n  ')
+  }
+
+  const copyCurl = async () => {
+    try {
+      const curlCommand = generateCurl()
+      await navigator.clipboard.writeText(curlCommand)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    } catch (err) {
+      console.error('Failed to copy:', err)
+      // Fallback for older browsers
+      const textArea = document.createElement('textarea')
+      textArea.value = generateCurl()
+      textArea.style.position = 'fixed'
+      textArea.style.opacity = '0'
+      document.body.appendChild(textArea)
+      textArea.select()
+      try {
+        document.execCommand('copy')
+        setCopied(true)
+        setTimeout(() => setCopied(false), 2000)
+      } catch (fallbackErr) {
+        console.error('Fallback copy failed:', fallbackErr)
+      }
+      document.body.removeChild(textArea)
+    }
+  }
+
   const executeRequest = async () => {
     setLoading(true)
     setResponse(null)
@@ -282,14 +363,46 @@ const ApiExplorer = ({ data, selectedItem }) => {
           </div>
         )}
 
-        <button
-          onClick={executeRequest}
-          disabled={loading}
-          className="btn-primary w-full reveal"
-          style={{ animationDelay: '300ms' }}
-        >
-          {loading ? 'Sending...' : 'Send Request'}
-        </button>
+        <div className="reveal" style={{ animationDelay: '300ms' }}>
+          <button
+            onClick={() => setShowCurlPreview(!showCurlPreview)}
+            className="btn-secondary w-full mb-3 flex items-center justify-between"
+          >
+            <span className="flex items-center gap-2">
+              <span>💻</span>
+              <span>{showCurlPreview ? 'Hide' : 'Show'} cURL Command</span>
+            </span>
+            <span>{showCurlPreview ? '▲' : '▼'}</span>
+          </button>
+          
+          {showCurlPreview && (
+            <div className="mb-3 surface border-2 border-black bg-white p-4">
+              <div className="flex items-center justify-between mb-2">
+                <p className="text-[0.65rem] uppercase tracking-[0.3em] text-black/60 font-bold">cURL Command</p>
+                <button
+                  onClick={copyCurl}
+                  className="text-xs btn-secondary px-2 py-1"
+                  title="Copy cURL command"
+                >
+                  {copied ? '✓ Copied!' : '📋 Copy'}
+                </button>
+              </div>
+              <pre className="text-xs font-mono text-black overflow-x-auto whitespace-pre-wrap break-words">
+                {generateCurl()}
+              </pre>
+            </div>
+          )}
+        </div>
+
+        <div className="reveal space-y-3" style={{ animationDelay: '320ms' }}>
+          <button
+            onClick={executeRequest}
+            disabled={loading}
+            className="btn-primary w-full"
+          >
+            {loading ? 'Sending...' : 'Send Request'}
+          </button>
+        </div>
 
         {response && (
           <div className="reveal" style={{ animationDelay: '320ms' }}>

data/frontend/src/components/Sidebar.jsx

@@ -100,16 +100,6 @@ const Sidebar = ({ data, activeView, setActiveView, selectedItem, setSelectedIte
       <div className="p-6 border-b-0 border-black/10 relative" style={{ borderBottomWidth: '3px' }}>
         <div className="pill text-[0.65rem] text-black mb-3 bg-white">ElderDocs</div>
         <h1 className="font-black text-3xl tracking-tight text-black uppercase font-['Syne']">API Space</h1>
-        <div className="mt-4 mb-2">
-          <a
-            href="/docs/ui"
-            target="_blank"
-            rel="noopener noreferrer"
-            className="text-xs text-black/60 hover:text-black underline font-medium"
-          >
-            ⚙️ Configure UI
-          </a>
-        </div>
         <div className="flex gap-2 mt-6">
           <button
             onClick={() => {

data/lib/elder_docs/cli.rb

@@ -14,28 +14,21 @@ module ElderDocs
     method_option :force_build, type: :boolean, default: false, desc: 'Force rebuilding frontend assets'
     
     def deploy
-      say '🚀 Starting ElderDocs deployment...', :green
-      
-      definitions_path = options[:definitions]
-      articles_path = options[:articles]
-      
-      unless File.exist?(definitions_path)
-        say "❌ Error: #{definitions_path} not found in current directory", :red
-        exit 1
-      end
-      
-      unless File.exist?(articles_path)
-        say "⚠️  Warning: #{articles_path} not found. Creating empty articles file...", :yellow
-        File.write(articles_path, [].to_json)
-      end
+      say '🚀 Building ElderDocs frontend...', :green
+      say '📝 Note: definitions.json and articles.json are loaded dynamically at runtime', :cyan
+      say '   No need to rebuild when you update your API definitions!', :cyan
+      say ''
       
       output_path = File.expand_path(options[:output] || default_output_path, Dir.pwd)
-      
       ElderDocs.config.output_path = output_path
       
+      # Reload config to get latest settings
+      ElderDocs.config.load_config_file
+      
+      # Build frontend only (no data compilation needed)
       generator = Generator.new(
-        definitions_path: definitions_path,
-        articles_path: articles_path,
+        definitions_path: nil,  # Not needed for dynamic mode
+        articles_path: nil,      # Not needed for dynamic mode
         output_path: output_path,
         api_server: options[:api_server],
         skip_build: options[:skip_build],
@@ -43,9 +36,12 @@ module ElderDocs
       )
       
       begin
-        generator.generate!
-        say '✅ Documentation generated successfully!', :green
+        generator.build_frontend_only!
+        say '✅ Frontend built successfully!', :green
         say "📦 Assets placed in: #{generator.output_path}", :cyan
+        say ''
+        say '✨ Your documentation is now live!', :green
+        say '   Edit definitions.json and articles.json - changes appear instantly!', :cyan
       rescue Generator::ValidationError => e
         say "❌ Validation Error: #{e.message}", :red
         exit 1

data/lib/elder_docs/config.rb

@@ -5,7 +5,7 @@ require 'pathname'
 
 module ElderDocs
   class Config
-    attr_accessor :mount_path, :api_server, :auth_types, :ui_config, :admin_password, :output_path
+    attr_accessor :mount_path, :api_server, :auth_types, :ui_config, :admin_password, :output_path, :definitions_file, :articles_file
     
     def initialize
       @mount_path = nil
@@ -15,6 +15,8 @@ module ElderDocs
       @admin_password = nil
       @api_servers = []
       @output_path = default_output_path
+      @definitions_file = nil
+      @articles_file = nil
       load_config_file
     end
     
@@ -40,6 +42,8 @@ module ElderDocs
         @auth_types = config['auth_types'] if config['auth_types']
         @ui_config = config['ui'] if config['ui']  # YAML uses 'ui' key, but we store as ui_config
         @admin_password = config['admin_password'] if config['admin_password']
+        @definitions_file = config['definitions_file'] if config['definitions_file']
+        @articles_file = config['articles_file'] if config['articles_file']
         if config['output_path']
           @output_path = File.expand_path(config['output_path'], config_dir)
         end

data/lib/elder_docs/engine/api_controller.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ElderDocs
+  class Engine
+    class ApiController < ActionController::API
+      include ActionController::MimeResponds
+      
+      def definitions
+        definitions_path = find_definitions_file
+        if definitions_path && File.exist?(definitions_path)
+          render json: JSON.parse(File.read(definitions_path, encoding: 'UTF-8'))
+        else
+          render json: { error: 'definitions.json not found' }, status: :not_found
+        end
+      end
+      
+      def articles
+        articles_path = find_articles_file
+        if articles_path && File.exist?(articles_path)
+          render json: JSON.parse(File.read(articles_path, encoding: 'UTF-8'))
+        else
+          render json: []
+        end
+      end
+      
+      def config
+        # Reload config to get latest from elderdocs.yml
+        ElderDocs.config.load_config_file
+        
+        config_data = {
+          api_server: ElderDocs.config.api_server,
+          api_servers: ElderDocs.config.api_servers || [],
+          auth_types: ElderDocs.config.auth_types || ['bearer', 'api_key', 'basic', 'oauth2'],
+          ui_config: ElderDocs.config.ui_config || {}
+        }
+        
+        render json: config_data
+      end
+      
+      private
+      
+      def find_definitions_file
+        config = ElderDocs.config
+        
+        # Check config file for definitions_file path
+        if config.respond_to?(:definitions_file) && config.definitions_file
+          config_path = find_config_file
+          if config_path
+            config_dir = File.dirname(config_path)
+            definitions_path = File.expand_path(config.definitions_file, config_dir)
+            return definitions_path if File.exist?(definitions_path)
+          end
+        end
+        
+        # Fallback to standard locations
+        paths = []
+        if defined?(Rails) && Rails.root
+          paths << Rails.root.join('definitions.json').to_s
+          paths << Rails.root.join('elderdocs', 'definitions.json').to_s
+        end
+        paths << File.join(Dir.pwd, 'definitions.json')
+        paths << File.join(Dir.pwd, 'elderdocs', 'definitions.json')
+        
+        paths.find { |path| File.exist?(path) }
+      end
+      
+      def find_articles_file
+        config = ElderDocs.config
+        
+        # Check config file for articles_file path
+        if config.respond_to?(:articles_file) && config.articles_file
+          config_path = find_config_file
+          if config_path
+            config_dir = File.dirname(config_path)
+            articles_path = File.expand_path(config.articles_file, config_dir)
+            return articles_path if File.exist?(articles_path)
+          end
+        end
+        
+        # Fallback to standard locations
+        paths = []
+        if defined?(Rails) && Rails.root
+          paths << Rails.root.join('articles.json').to_s
+          paths << Rails.root.join('elderdocs', 'articles.json').to_s
+        end
+        paths << File.join(Dir.pwd, 'articles.json')
+        paths << File.join(Dir.pwd, 'elderdocs', 'articles.json')
+        
+        paths.find { |path| File.exist?(path) } || create_empty_articles_file
+      end
+      
+      def create_empty_articles_file
+        # Create empty articles.json if it doesn't exist
+        default_path = if defined?(Rails) && Rails.root
+          Rails.root.join('articles.json').to_s
+        else
+          File.join(Dir.pwd, 'articles.json')
+        end
+        
+        File.write(default_path, [].to_json) unless File.exist?(default_path)
+        default_path
+      end
+      
+      def find_config_file
+        config_paths = []
+        if defined?(Rails) && Rails.root
+          config_paths << Rails.root.join('elderdocs.yml').to_s
+        end
+        config_paths << File.join(Dir.pwd, 'elderdocs.yml')
+        config_paths.find { |path| File.exist?(path) }
+      end
+    end
+  end
+end
+

data/lib/elder_docs/engine.rb

@@ -8,15 +8,12 @@ module ElderDocs
     
     # Define routes inline
     routes do
-      # UI Configuration endpoints (before catch-all)
-      get '/ui', to: 'engine/ui_config#show'
-      get '/ui/login', to: 'engine/ui_config#show_login'
-      post '/ui/login', to: 'engine/ui_config#login'
-      post '/ui/logout', to: 'engine/ui_config#logout'
-      post '/ui/config', to: 'engine/ui_config#update'
+      # API endpoints for dynamic data
+      get '/api/definitions', to: 'engine/api#definitions'
+      get '/api/articles', to: 'engine/api#articles'
+      get '/api/config', to: 'engine/api#config'
       
-      # Serve data.js explicitly before catch-all
-      get '/data.js', to: 'engine/docs#show', defaults: { path: 'data.js' }
+      # Serve static assets
       root 'engine/docs#show', defaults: { path: 'index.html' }
       get '/*path', to: 'engine/docs#show', defaults: { path: 'index.html' }
     end
@@ -40,8 +37,8 @@ module ElderDocs
       end
     end
     
-    # Load UI config controller
-    require_relative 'engine/ui_config_controller'
+    # Load API controller
+    require_relative 'engine/api_controller'
     
     # Create a simple controller to serve the static files
     # Use API base to avoid CSRF protection

data/lib/elder_docs/generator.rb

@@ -40,6 +40,20 @@ module ElderDocs
       end
     end
     
+    def build_frontend_only!
+      # Build frontend without data compilation (for dynamic mode)
+      # Check if assets already exist
+      assets_exist = File.exist?(File.join(output_path, 'index.html'))
+      
+      if skip_build || (assets_exist && !force_build)
+        say '⏭️  Skipping frontend build (assets already exist)', :yellow
+        say '💡 Run with --force-build to rebuild', :cyan
+      else
+        build_frontend!
+        copy_assets!
+      end
+    end
+    
     private
     
     def validate_definitions!
@@ -207,10 +221,12 @@ module ElderDocs
       
       frontend_dir = File.expand_path(frontend_dir)
       
-      # Write compiled data to frontend public directory
-      public_dir = File.join(frontend_dir, 'public')
-      FileUtils.mkdir_p(public_dir)
-      File.write(File.join(public_dir, 'data.js'), @compiled_data_js)
+      # Write compiled data to frontend public directory (only if in static mode)
+      if @compiled_data_js
+        public_dir = File.join(frontend_dir, 'public')
+        FileUtils.mkdir_p(public_dir)
+        File.write(File.join(public_dir, 'data.js'), @compiled_data_js)
+      end
       
       # Check if node_modules exists, if not, run npm install
       node_modules = File.join(frontend_dir, 'node_modules')

data/lib/elder_docs/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module ElderDocs
-  VERSION = '0.1.4'
+  VERSION = '0.1.5'
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elder_docs
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - ElderDocs
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-24 00:00:00.000000000 Z
+date: 2025-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -131,10 +131,11 @@ files:
 - lib/elder_docs/cli.rb
 - lib/elder_docs/config.rb
 - lib/elder_docs/engine.rb
+- lib/elder_docs/engine/api_controller.rb
 - lib/elder_docs/engine/ui_config_controller.rb
 - lib/elder_docs/generator.rb
 - lib/elder_docs/version.rb
-homepage: https://github.com/yashdave31/elder_docs
+homepage: https://github.com/yashdave31/elderdocs
 licenses:
 - MIT
 metadata: {}