docyard 0.0.1 → 0.2.0

data/lib/docyard/initializer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Docyard
+  class Initializer
+    DOCS_DIR = "docs"
+    TEMPLATE_DIR = File.join(__dir__, "templates", "markdown")
+
+    TEMPLATES = {
+      "index.md" => "index.md.erb",
+      "getting-started/introduction.md" => "getting-started/introduction.md.erb",
+      "getting-started/installation.md" => "getting-started/installation.md.erb",
+      "getting-started/quick-start.md" => "getting-started/quick-start.md.erb",
+      "core-concepts/file-structure.md" => "core-concepts/file-structure.md.erb",
+      "core-concepts/markdown.md" => "core-concepts/markdown.md.erb"
+    }.freeze
+
+    def initialize(path = ".")
+      @path = path
+      @docs_path = File.join(@path, DOCS_DIR)
+    end
+
+    def run
+      if already_initialized?
+        print_already_exists_error
+        return
+      end
+
+      create_structure
+      print_success
+      true
+    end
+
+    private
+
+    def already_initialized?
+      File.exist?(@docs_path)
+    end
+
+    def create_structure
+      FileUtils.mkdir_p(@docs_path)
+
+      TEMPLATES.each do |output_name, template_name|
+        copy_template(template_name, output_name)
+      end
+    end
+
+    def copy_template(template_name, output_name)
+      template_path = File.join(TEMPLATE_DIR, template_name)
+      output_path = File.join(@docs_path, output_name)
+
+      output_dir = File.dirname(output_path)
+      FileUtils.mkdir_p(output_dir) unless File.directory?(output_dir)
+
+      content = File.read(template_path)
+      File.write(output_path, content)
+    end
+
+    def print_already_exists_error
+      puts "Error: #{DOCS_DIR}/ folder already exists"
+      puts "   Remove it first or run docyard in a different directory"
+    end
+
+    def print_success
+      puts "Docyard initialized successfully!"
+      puts ""
+      puts "Created:"
+      TEMPLATES.each_key { |file| puts "  #{DOCS_DIR}/#{file}" }
+      puts ""
+      puts "Next steps:"
+      puts "  1. Edit your markdown files in #{DOCS_DIR}/"
+      puts "  2. Run 'docyard serve' to preview your documentation locally"
+    end
+  end
+end

data/lib/docyard/logging.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Docyard
+  module Logging
+    class << self
+      attr_writer :logger
+
+      def logger
+        @logger ||= default_logger
+      end
+
+      def level=(level)
+        logger.level = Logger.const_get(level.to_s.upcase)
+      end
+
+      private
+
+      def default_logger
+        logger = Logger.new($stdout)
+        logger.level = Logger::INFO
+        logger.formatter = log_formatter
+        logger
+      end
+
+      def log_formatter
+        proc do |severity, datetime, _progname, msg|
+          timestamp = datetime.strftime("%Y-%m-%d %H:%M:%S")
+          "[#{timestamp}] [Docyard] [#{severity}] #{msg}\n"
+        end
+      end
+    end
+  end
+
+  def self.logger
+    Logging.logger
+  end
+
+  def self.log_level=(level)
+    Logging.level = level
+  end
+end

data/lib/docyard/markdown.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+require "yaml"
+
+module Docyard
+  class Markdown
+    FRONTMATTER_REGEX = /\A---\s*\n(.*?\n)---\s*\n/m
+
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw.freeze
+    end
+
+    def frontmatter
+      @frontmatter ||= parse_frontmatter
+    end
+
+    def content
+      @content ||= extract_content
+    end
+
+    def html
+      @html ||= render_html
+    end
+
+    def title
+      frontmatter["title"]
+    end
+
+    def description
+      frontmatter["description"]
+    end
+
+    private
+
+    def parse_frontmatter
+      match = raw.match(FRONTMATTER_REGEX)
+      return {} unless match
+
+      YAML.safe_load(match[1])
+    rescue Psych::SyntaxError
+      {}
+    end
+
+    def extract_content
+      raw.sub(FRONTMATTER_REGEX, "").strip
+    end
+
+    def render_html
+      Kramdown::Document.new(
+        content,
+        input: "GFM",
+        hard_wrap: false,
+        syntax_highlighter: "rouge"
+      ).to_html
+    end
+  end
+end

data/lib/docyard/rack_application.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "rack"
+require_relative "sidebar_builder"
+
+module Docyard
+  class RackApplication
+    def initialize(docs_path:, file_watcher:)
+      @docs_path = docs_path
+      @file_watcher = file_watcher
+      @router = Router.new(docs_path: docs_path)
+      @renderer = Renderer.new
+      @asset_handler = AssetHandler.new
+    end
+
+    def call(env)
+      handle_request(env)
+    end
+
+    private
+
+    attr_reader :docs_path, :file_watcher, :router, :renderer, :asset_handler
+
+    def handle_request(env)
+      path = env["PATH_INFO"]
+
+      return handle_reload_check(env) if path == Constants::RELOAD_ENDPOINT
+      return asset_handler.serve(path) if path.start_with?(Constants::ASSETS_PREFIX)
+
+      handle_documentation_request(path)
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    def handle_documentation_request(path)
+      result = router.resolve(path)
+
+      if result.found?
+        sidebar = SidebarBuilder.new(docs_path: docs_path, current_path: path)
+        html = renderer.render_file(result.file_path, sidebar_html: sidebar.to_html)
+        [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
+      else
+        html = renderer.render_not_found
+        [Constants::STATUS_NOT_FOUND, { "Content-Type" => Constants::CONTENT_TYPE_HTML }, [html]]
+      end
+    end
+
+    def handle_reload_check(env)
+      since = parse_since_timestamp(env)
+      reload_needed = file_watcher.changed_since?(since)
+
+      build_reload_response(reload_needed)
+    rescue StandardError => e
+      log_reload_error(e)
+      build_reload_response(false)
+    end
+
+    def parse_since_timestamp(env)
+      query = Rack::Utils.parse_query(env["QUERY_STRING"])
+      query["since"] ? Time.at(query["since"].to_f) : Time.now
+    end
+
+    def log_reload_error(error)
+      Docyard.logger.error "Reload check error: #{error.message}"
+      Docyard.logger.debug error.backtrace.join("\n")
+    end
+
+    def build_reload_response(reload_needed)
+      response_body = { reload: reload_needed, timestamp: Time.now.to_f }.to_json
+      [Constants::STATUS_OK, { "Content-Type" => Constants::CONTENT_TYPE_JSON }, [response_body]]
+    end
+
+    def handle_error(error)
+      Docyard.logger.error "Request error: #{error.message}"
+      Docyard.logger.debug error.backtrace.join("\n")
+      [Constants::STATUS_INTERNAL_ERROR, { "Content-Type" => Constants::CONTENT_TYPE_HTML },
+       [renderer.render_server_error(error)]]
+    end
+  end
+end

data/lib/docyard/renderer.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Docyard
+  class Renderer
+    LAYOUTS_PATH = File.join(__dir__, "templates", "layouts")
+    ERRORS_PATH = File.join(__dir__, "templates", "errors")
+
+    attr_reader :layout_path
+
+    def initialize(layout: "default")
+      @layout_path = File.join(LAYOUTS_PATH, "#{layout}.html.erb")
+    end
+
+    def render_file(file_path, sidebar_html: "")
+      markdown_content = File.read(file_path)
+      markdown = Markdown.new(markdown_content)
+
+      html_content = strip_md_from_links(markdown.html)
+
+      render(
+        content: html_content,
+        page_title: markdown.title || "Documentation",
+        sidebar_html: sidebar_html
+      )
+    end
+
+    def render(content:, page_title: "Documentation", sidebar_html: "")
+      template = File.read(layout_path)
+
+      @content = content
+      @page_title = page_title
+      @sidebar_html = sidebar_html
+
+      ERB.new(template).result(binding)
+    end
+
+    def render_not_found
+      render_error_template(404)
+    end
+
+    def render_server_error(error)
+      @error_message = error.message
+      @backtrace = error.backtrace.join("\n")
+      render_error_template(500)
+    end
+
+    def render_error_template(status)
+      error_template_path = File.join(ERRORS_PATH, "#{status}.html.erb")
+      template = File.read(error_template_path)
+      ERB.new(template).result(binding)
+    end
+
+    private
+
+    def strip_md_from_links(html)
+      html.gsub(/href="([^"]+)\.md"/, 'href="\1"')
+    end
+  end
+end

data/lib/docyard/router.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Docyard
+  class Router
+    attr_reader :docs_path
+
+    def initialize(docs_path:)
+      @docs_path = docs_path
+    end
+
+    def resolve(request_path)
+      clean_path = sanitize_path(request_path)
+
+      file_path = File.join(docs_path, "#{clean_path}#{Constants::MARKDOWN_EXTENSION}")
+      return Routing::ResolutionResult.found(file_path) if File.file?(file_path)
+
+      index_path = File.join(docs_path, clean_path, "#{Constants::INDEX_FILE}#{Constants::MARKDOWN_EXTENSION}")
+      return Routing::ResolutionResult.found(index_path) if File.file?(index_path)
+
+      Routing::ResolutionResult.not_found
+    end
+
+    private
+
+    def sanitize_path(request_path)
+      clean = request_path.delete_prefix("/")
+      clean = Constants::INDEX_FILE if clean.empty?
+      clean.delete_suffix(Constants::MARKDOWN_EXTENSION)
+    end
+  end
+end

data/lib/docyard/routing/resolution_result.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Routing
+    class ResolutionResult
+      attr_reader :file_path, :status
+
+      def self.found(file_path)
+        new(file_path: file_path, status: :found)
+      end
+
+      def self.not_found
+        new(file_path: nil, status: :not_found)
+      end
+
+      def initialize(file_path:, status:)
+        @file_path = file_path
+        @status = status
+        freeze
+      end
+
+      def found?
+        status == :found
+      end
+
+      def not_found?
+        status == :not_found
+      end
+    end
+  end
+end

data/lib/docyard/server.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "webrick"
+require "stringio"
+require_relative "file_watcher"
+require_relative "rack_application"
+
+module Docyard
+  class Server
+    DEFAULT_PORT = 4200
+    DEFAULT_HOST = "localhost"
+
+    attr_reader :port, :host, :docs_path
+
+    def initialize(port: DEFAULT_PORT, host: DEFAULT_HOST, docs_path: "docs")
+      @port = port
+      @host = host
+      @docs_path = docs_path
+      @file_watcher = FileWatcher.new(File.expand_path(docs_path))
+      @app = RackApplication.new(
+        docs_path: File.expand_path(docs_path),
+        file_watcher: @file_watcher
+      )
+    end
+
+    def start
+      validate_docs_directory!
+      print_server_info
+      @file_watcher.start
+
+      http_server.mount_proc("/") { |req, res| handle_request(req, res) }
+      trap("INT") { shutdown_server }
+
+      http_server.start
+      @file_watcher.stop
+    end
+
+    private
+
+    def validate_docs_directory!
+      return if File.directory?(docs_path)
+
+      abort "Error: #{docs_path}/ directory not found.\n" \
+            "Run `docyard init` first to create the docs structure."
+    end
+
+    def print_server_info
+      puts "Starting Docyard server..."
+      puts "=> Serving docs from: #{docs_path}/"
+      puts "=> Running at: http://#{host}:#{port}"
+      puts "=> Press Ctrl+C to stop\n"
+    end
+
+    def shutdown_server
+      puts "\nShutting down server..."
+      http_server.shutdown
+    end
+
+    def http_server
+      @http_server ||= WEBrick::HTTPServer.new(
+        Port: port,
+        BindAddress: host,
+        AccessLog: [],
+        Logger: WEBrick::Log.new(File::NULL)
+      )
+    end
+
+    def handle_request(req, res)
+      env = build_rack_env(req)
+      status, headers, body = @app.call(env)
+
+      res.status = status
+      headers.each { |key, value| res[key] = value }
+      body.each { |chunk| res.body << chunk }
+    end
+
+    def build_rack_env(req)
+      {
+        "REQUEST_METHOD" => req.request_method,
+        "PATH_INFO" => req.path,
+        "QUERY_STRING" => req.query_string || "",
+        "SERVER_NAME" => req.host,
+        "SERVER_PORT" => req.port.to_s,
+        "rack.version" => Rack::VERSION,
+        "rack.url_scheme" => "http",
+        "rack.input" => StringIO.new,
+        "rack.errors" => $stderr
+      }
+    end
+  end
+end

data/lib/docyard/sidebar/file_system_scanner.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class FileSystemScanner
+      attr_reader :docs_path
+
+      def initialize(docs_path)
+        @docs_path = docs_path
+      end
+
+      def scan
+        return [] unless File.directory?(docs_path)
+
+        scan_directory(docs_path, "")
+      end
+
+      private
+
+      def scan_directory(base_path, relative_path)
+        full_path = File.join(base_path, relative_path)
+        return [] unless File.directory?(full_path)
+
+        entries = sorted_entries(full_path, relative_path)
+        entries.map { |entry| build_item(entry, base_path, relative_path, full_path) }.compact
+      end
+
+      def sorted_entries(full_path, relative_path)
+        Dir.children(full_path)
+          .reject { |entry| hidden_or_ignored?(entry, relative_path) }
+          .sort_by { |entry| sort_key(entry) }
+      end
+
+      def build_item(entry, base_path, relative_path, full_path)
+        entry_full_path = File.join(full_path, entry)
+        entry_relative_path = build_relative_path(relative_path, entry)
+
+        if File.directory?(entry_full_path)
+          build_directory_item(entry, entry_relative_path, base_path)
+        elsif entry.end_with?(".md")
+          build_file_item(entry, entry_relative_path)
+        end
+      end
+
+      def build_relative_path(relative_path, entry)
+        relative_path.empty? ? entry : File.join(relative_path, entry)
+      end
+
+      def build_directory_item(entry, entry_relative_path, base_path)
+        {
+          type: :directory,
+          name: entry,
+          path: entry_relative_path,
+          children: scan_directory(base_path, entry_relative_path)
+        }
+      end
+
+      def build_file_item(entry, entry_relative_path)
+        {
+          type: :file,
+          name: entry.delete_suffix(".md"),
+          path: entry_relative_path
+        }
+      end
+
+      def hidden_or_ignored?(entry, relative_path)
+        entry.start_with?(".") ||
+          entry.start_with?("_") ||
+          (entry == "index.md" && relative_path.empty?)
+      end
+
+      def sort_key(entry)
+        entry.downcase
+      end
+    end
+  end
+end

data/lib/docyard/sidebar/renderer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Docyard
+  module Sidebar
+    class Renderer
+      PARTIALS_PATH = File.join(__dir__, "../templates/partials")
+
+      attr_reader :site_title
+
+      def initialize(site_title: "Documentation")
+        @site_title = site_title
+      end
+
+      def render(tree)
+        return "" if tree.empty?
+
+        nav_content = render_tree_with_sections(tree)
+        footer_html = render_partial(:sidebar_footer)
+
+        render_partial(:sidebar, nav_content: nav_content, footer_html: footer_html)
+      end
+
+      private
+
+      def render_partial(name, locals = {})
+        template_path = File.join(PARTIALS_PATH, "_#{name}.html.erb")
+        template = File.read(template_path)
+
+        locals.each { |key, value| instance_variable_set("@#{key}", value) }
+
+        erb_binding = binding
+        ERB.new(template).result(erb_binding)
+      end
+
+      def icon(name)
+        render_partial(:icons, icon_name: name)
+      end
+
+      def render_tree_with_sections(items)
+        filtered_items = items.reject { |item| item[:title]&.downcase == site_title.downcase }
+        grouped_items = group_by_section(filtered_items)
+
+        grouped_items.map do |section_name, section_items|
+          render_section(section_name, section_items)
+        end.join
+      end
+
+      def render_section(section_name, section_items)
+        section_content = render_tree(section_items)
+        render_partial(:nav_section, section_name: section_name, section_content: section_content)
+      end
+
+      def group_by_section(items)
+        sections = {}
+        root_items = []
+
+        items.each do |item|
+          process_section_item(item, sections, root_items)
+        end
+
+        build_section_result(sections, root_items)
+      end
+
+      def process_section_item(item, sections, root_items)
+        return if item[:title]&.downcase == site_title.downcase
+
+        if item[:type] == :directory && !item[:children].empty?
+          section_name = item[:title].upcase
+          sections[section_name] = item[:children]
+        else
+          root_items << item
+        end
+      end
+
+      def build_section_result(sections, root_items)
+        result = {}
+        result[nil] = root_items unless root_items.empty?
+        result.merge!(sections)
+      end
+
+      def render_tree(items)
+        return "" if items.empty?
+
+        list_items = items.map { |item| render_item(item) }.join
+        render_partial(:nav_list, list_items: list_items)
+      end
+
+      def render_item(item)
+        item_content = if item[:children].empty?
+                         render_leaf_item(item)
+                       else
+                         render_group_item(item)
+                       end
+
+        render_partial(:nav_item, item_content: item_content)
+      end
+
+      def render_leaf_item(item)
+        render_partial(:nav_leaf, path: item[:path], title: item[:title], active: item[:active])
+      end
+
+      def render_group_item(item)
+        children_html = render_tree(item[:children])
+        render_partial(:nav_group, title: item[:title], children_html: children_html)
+      end
+    end
+  end
+end

data/lib/docyard/sidebar/title_extractor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Docyard
+  module Sidebar
+    class TitleExtractor
+      def extract(file_path)
+        return titleize_filename(file_path) unless File.file?(file_path)
+
+        content = File.read(file_path)
+        markdown = Markdown.new(content)
+        markdown.title || titleize_filename(file_path)
+      rescue StandardError => e
+        Docyard.logger.warn "Failed to extract title from #{file_path}: #{e.message}"
+        titleize_filename(file_path)
+      end
+
+      private
+
+      def titleize_filename(file_path)
+        filename = File.basename(file_path, Constants::MARKDOWN_EXTENSION)
+        Utils::TextFormatter.titleize(filename)
+      end
+    end
+  end
+end