zard-doc 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4a7ff58279b52ea8ca3e15ffdf25f54214d20c5ececaeb641282e85050d3d5a
+  data.tar.gz: 9ede39071e88157e47387cf29ae4b4c04a8af656c396e26c783824b671c52ce4
+SHA512:
+  metadata.gz: ed9d9d91a23b003910e34db882cfec727154822a60bf66c92e2f996bd9c2c94d0796c15e9603be569846b43985585eae8f74a24a722ca0fe3e60b7d985217ebe
+  data.tar.gz: 9d9d1e2a24d28de2d6080bc397734ab2f1de2d4623dc9cc4c3e70335e3801c0e8ee6d3aeff7b48e36a1234fd3d950407eb660d7452e9ab0c0f31c2a1ec657d45

data/LICENSE

@@ -0,0 +1,5 @@
+Mozilla Public License Version 2.0
+==================================
+
+This package is distributed under the Mozilla Public License 2.0.
+The complete license text is available at https://mozilla.org/MPL/2.0/.

data/README.md

@@ -0,0 +1,46 @@
+# zard-doc
+
+`zard-doc` renders API documentation from the versioned model produced by `zard`.
+
+See the [ZARD usage guide](https://github.com/rigortype/zard/blob/master/docs/usage.md) for installation, canonical tag syntax, model access, limitations, and exit codes. The `0.0.1` candidate is not yet published on RubyGems. Until then, install both gems from the repository:
+
+```ruby
+gem "zard", github: "rigortype/zard"
+gem "zard-doc", github: "rigortype/zard"
+```
+
+After publication, use the released pair:
+
+```ruby
+gem "zard", "~> 0.0.1"
+gem "zard-doc", "~> 0.0.1"
+```
+
+```ruby
+require "zard"
+require "zard/doc"
+
+document = Zard.parse(source, path: "lib/example.rb")
+markdown = Zard::Doc.render(document)
+```
+
+Descriptions may continue across plain comment lines until the next annotation or contract.
+
+Run the linter against Ruby source files with:
+
+```console
+zard-doc lint lib
+zard-doc lint --fail-on warning lib/example.rb
+```
+
+Render Markdown to standard output with:
+
+```console
+zard-doc render lib
+```
+
+Directories are searched recursively for Ruby source files. Files are processed in stable sorted order and duplicate paths are ignored.
+Unreadable inputs are reported together; rendering never emits partial Markdown when any input cannot be read.
+Use `-` as a path to read Ruby source from standard input.
+
+`lint` exits with 0 when no diagnostic meets the configured failure threshold, 1 when a diagnostic meets it, and 2 for invalid usage or unreadable input. The default threshold is `error`; `--fail-on warning` also fails on warnings. `render` exits with 1 for error diagnostics, 2 for invalid usage or unreadable input, and 0 otherwise. Diagnostics go to standard error for `render`; lint diagnostics go to standard output.

data/exe/zard-doc

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "zard/doc/cli"
+
+exit Zard::Doc::CLI.run(ARGV)

data/lib/zard/doc/cli.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "zard/doc"
+
+module Zard
+  module Doc
+    class CLI
+      SEVERITY_RANK = {error: 2, warning: 1, info: 0}.freeze
+
+      def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+        new(argv, stdin, stdout, stderr).run
+      end
+
+      def initialize(argv, stdin, stdout, stderr)
+        @argv = argv.dup
+        @stdin = stdin
+        @stdout = stdout
+        @stderr = stderr
+        @fail_on = :error
+      end
+
+      def run
+        return help if @argv.first == "--help" || @argv.first == "-h"
+
+        case @argv.shift
+        when "lint"
+          lint_command
+        when "render"
+          render_command
+        else
+          usage_error("Expected the lint or render command.")
+        end
+      rescue OptionParser::ParseError => error
+        usage_error(error.message)
+      end
+
+      private
+
+      def lint_command
+        lint_option_parser.parse!(@argv)
+        return usage_error("Pass at least one Ruby source file.") if @argv.empty?
+
+        paths = source_paths(@argv)
+        return usage_error("No Ruby source files were found.") if paths.empty?
+
+        lint(paths)
+      end
+
+      def lint_option_parser
+        OptionParser.new do |parser|
+          parser.banner = usage
+          parser.on("--fail-on LEVEL", %w[error warning], "Minimum severity that exits unsuccessfully") do |level|
+            @fail_on = level.to_sym
+          end
+        end
+      end
+
+      def render_command
+        OptionParser.new.parse!(@argv)
+        return usage_error("Pass at least one Ruby source file.") if @argv.empty?
+
+        paths = source_paths(@argv)
+        return usage_error("No Ruby source files were found.") if paths.empty?
+
+        render(paths)
+      end
+
+      def source_paths(inputs)
+        inputs.flat_map do |input|
+          File.directory?(input) ? Dir.glob(File.join(input, "**", "*.rb")).sort : input
+        end.uniq.sort
+      end
+
+      def lint(paths)
+        failed = false
+        input_error = false
+
+        paths.each do |path|
+          source = read_source(path)
+          unless source
+            input_error = true
+            next
+          end
+
+          document = Zard.parse(source, path: path)
+          document.diagnostics.each do |diagnostic|
+            @stdout.puts format_diagnostic(diagnostic)
+            failed ||= failing?(diagnostic)
+          end
+        end
+
+        return 2 if input_error
+
+        failed ? 1 : 0
+      end
+
+      def render(paths)
+        documents = paths.filter_map do |path|
+          source = read_source(path)
+          Zard.parse(source, path: path) if source
+        end
+        return 2 if documents.length != paths.length
+
+        diagnostics = documents.flat_map(&:diagnostics)
+        diagnostics.each { |diagnostic| @stderr.puts format_diagnostic(diagnostic) }
+        return 1 if diagnostics.any? { |diagnostic| diagnostic.severity == :error }
+
+        markdown = documents.map { |document| Zard::Doc.render(document) }.reject(&:empty?).join("\n")
+        @stdout.print markdown
+        0
+      end
+
+      def read_source(path)
+        return @stdin.read if path == "-"
+
+        File.read(path)
+      rescue SystemCallError => error
+        @stderr.puts "#{path}: #{error.message}"
+        nil
+      end
+
+      def failing?(diagnostic)
+        SEVERITY_RANK.fetch(diagnostic.severity) >= SEVERITY_RANK.fetch(@fail_on)
+      end
+
+      def format_diagnostic(diagnostic)
+        span = diagnostic.span
+        "#{span.path}:#{span.start_line}:#{span.start_column + 1}: #{diagnostic.severity} #{diagnostic.code} #{diagnostic.message}"
+      end
+
+      def help
+        @stdout.puts usage
+        0
+      end
+
+      def usage_error(message)
+        @stderr.puts message
+        @stderr.puts usage
+        2
+      end
+
+      def usage
+        <<~USAGE.chomp
+          Usage:
+            zard-doc lint [--fail-on error|warning] PATH...
+            zard-doc render PATH...
+        USAGE
+      end
+    end
+  end
+end

data/lib/zard/doc/renderer.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Zard
+  module Doc
+    class Renderer
+      def self.render(document)
+        new(document).render
+      end
+
+      def initialize(document)
+        @document = document
+      end
+
+      def render
+        sections = @document.declarations.filter_map { |declaration| render_declaration(declaration) }
+        return "" if sections.empty?
+
+        "#{sections.join("\n\n")}\n"
+      end
+
+      private
+
+      def render_declaration(declaration)
+        return unless declaration.visibility == :public
+
+        documentation = declaration.documentation.reject { |tag| tag.name == :raw }
+        return if documentation.empty?
+
+        parts = [heading(declaration)]
+        parts << "Superclass: `#{declaration.superclass}`." if declaration.superclass
+        parts << render_container_builder(declaration) if declaration.container_builder
+        append_mixins(parts, declaration)
+        parts << "Alias of `#{display_alias_target(declaration)}`." if declaration.alias_target
+        text = documentation.select { |tag| tag.name == :text }.map(&:description)
+        parts << text.join("\n") unless text.empty?
+
+        deprecated = documentation.select { |tag| tag.name == :deprecated }
+        parts << "### Deprecated\n\n#{deprecated.map(&:description).join("\n\n")}" unless deprecated.empty?
+
+        notes = documentation.select { |tag| tag.name == :note }
+        parts << "### Notes\n\n#{notes.map(&:description).join("\n\n")}" unless notes.empty?
+
+        examples = documentation.select { |tag| tag.name == :example }
+        parts << "### Examples\n\n#{examples.map(&:description).join("\n\n")}" unless examples.empty?
+
+        parameters = documentation.select { |tag| tag.name == :param }
+        unless parameters.empty?
+          items = parameters.map { |tag| list_item("`#{tag.subject}` — ", tag.description) }
+          parts << "### Parameters\n\n#{items.join("\n")}"
+        end
+
+        returns = documentation.select { |tag| tag.name == :return }
+        parts << "### Returns\n\n#{returns.map(&:description).join("\n\n")}" unless returns.empty?
+
+        documentation.select { |tag| tag.name == :option }.group_by(&:owner).each do |owner, options|
+          items = options.map { |tag| list_item("`#{tag.subject}` — ", tag.description) }
+          parts << "### Options for `#{owner}`\n\n#{items.join("\n")}"
+        end
+
+        raises = documentation.select { |tag| tag.name == :raise }
+        unless raises.empty?
+          items = raises.map { |tag| list_item("`#{tag.subject}` — ", tag.description) }
+          parts << "### Raises\n\n#{items.join("\n")}"
+        end
+
+        yield_parameters = documentation.select { |tag| tag.name == :yieldparam }
+        unless yield_parameters.empty?
+          items = yield_parameters.map { |tag| list_item("`#{tag.subject}` — ", tag.description) }
+          parts << "### Yield parameters\n\n#{items.join("\n")}"
+        end
+
+        yield_returns = documentation.select { |tag| tag.name == :yieldreturn }
+        parts << "### Yields\n\n#{yield_returns.map(&:description).join("\n\n")}" unless yield_returns.empty?
+
+        see_also = documentation.select { |tag| tag.name == :see }
+        unless see_also.empty?
+          items = see_also.map { |tag| list_item("", tag.description) }
+          parts << "### See also\n\n#{items.join("\n")}"
+        end
+        parts.join("\n\n")
+      end
+
+      def heading(declaration)
+        return "## Alias `#{display_name(declaration)}`" if declaration.alias_target
+
+        case declaration.kind
+        when :class
+          "## Class `#{qualified_name(declaration)}`"
+        when :module
+          "## Module `#{qualified_name(declaration)}`"
+        when :constant
+          "## Constant `#{qualified_name(declaration)}`"
+        when :refinement
+          "## Refinement `#{refinement_owner(declaration)}`"
+        when :instance_attribute_reader, :singleton_attribute_reader
+          "## Attribute reader `#{display_name(declaration)}`"
+        when :instance_attribute_writer, :singleton_attribute_writer
+          "## Attribute writer `#{display_name(declaration)}`"
+        when :instance_attribute_accessor, :singleton_attribute_accessor
+          "## Attribute accessor `#{display_name(declaration)}`"
+        else
+          "## `#{display_name(declaration)}(#{declaration.parameters.join(", ")})`"
+        end
+      end
+
+      def append_mixins(parts, declaration)
+        {include: "Includes", prepend: "Prepends", extend: "Extends"}.each do |kind, heading|
+          targets = declaration.mixins.select { |mixin| mixin.kind == kind }.map(&:target)
+          parts << "### #{heading}\n\n#{targets.map { |target| "- `#{target}`" }.join("\n")}" unless targets.empty?
+        end
+      end
+
+      def render_container_builder(declaration)
+        builder = declaration.container_builder
+        label = if declaration.kind == :module
+          "Module builder"
+        else
+          "Class builder"
+        end
+        return "#{label}: `#{builder}`." unless builder.include?("\n")
+
+        "#{label}:\n\n```ruby\n#{dedent_continuation(builder)}\n```"
+      end
+
+      def dedent_continuation(source)
+        first, *continuation = source.lines(chomp: true)
+        margins = continuation.reject { |line| line.strip.empty? }.map { |line| line[/\A[\t ]*/].length }
+        margin = margins.min || 0
+        [first, *continuation.map { |line| line[margin..] }].join("\n")
+      end
+
+      def qualified_name(declaration)
+        [declaration.namespace, declaration.name].compact.join("::")
+      end
+
+      def display_name(declaration)
+        if declaration.refinement
+          separator = declaration.kind.to_s.start_with?("singleton_") ? "." : "#"
+          return "#{refinement_owner(declaration)}#{separator}#{declaration.name}"
+        end
+
+        if declaration.kind.to_s.start_with?("singleton_")
+          owner = singleton_owner(declaration)
+          return owner ? "#{owner}.#{declaration.name}" : declaration.name
+        end
+        return declaration.name unless declaration.namespace
+
+        "#{declaration.namespace}##{declaration.name}"
+      end
+
+      def display_alias_target(declaration)
+        if declaration.refinement
+          separator = declaration.kind.to_s.start_with?("singleton_") ? "." : "#"
+          return "#{refinement_owner(declaration)}#{separator}#{declaration.alias_target}"
+        end
+
+        if declaration.kind.to_s.start_with?("singleton_")
+          owner = singleton_owner(declaration)
+          return owner ? "#{owner}.#{declaration.alias_target}" : declaration.alias_target
+        end
+        return declaration.alias_target unless declaration.namespace
+
+        "#{declaration.namespace}##{declaration.alias_target}"
+      end
+
+      def singleton_owner(declaration)
+        return declaration.receiver unless declaration.receiver.nil? || declaration.receiver == "self"
+
+        declaration.namespace || declaration.receiver
+      end
+
+      def refinement_owner(declaration)
+        namespace = declaration.namespace
+        target = declaration.refinement || declaration.name
+        namespace ? "#{namespace}[#{target}]" : "[#{target}]"
+      end
+
+      def list_item(prefix, description)
+        first, *continuation = description.split("\n", -1)
+        lines = ["- #{prefix}#{first}"]
+        continuation.each { |line| lines << (line.empty? ? "" : "  #{line}") }
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/zard/doc/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Zard
+  module Doc
+    VERSION = "0.0.1"
+  end
+end

data/lib/zard/doc.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "zard"
+require_relative "doc/version"
+require_relative "doc/renderer"
+
+module Zard
+  module Doc
+    def self.render(document)
+      Renderer.render(document)
+    end
+
+    private_constant :Renderer
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: zard-doc
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- USAMI Kenta
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+description: zard-doc renders API documentation from the versioned ZARD document model.
+email:
+- tadsan@zonu.me
+executables:
+- zard-doc
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/zard-doc
+- lib/zard/doc.rb
+- lib/zard/doc/cli.rb
+- lib/zard/doc/renderer.rb
+- lib/zard/doc/version.rb
+homepage: https://github.com/rigortype/zard
+licenses:
+- MPL-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rigortype/zard
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/rigortype/zard
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Markdown API documentation for ZARD
+test_files: []