smart_config 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 025b4afefa2ea50c75c77001460628df27241849a6ccb090dd948a4926db80ce
-  data.tar.gz: 1ca3075c54be54c5a4c11eb0da918c2e7fe1947691bdc9ffc79f55dc70798fa2
+  metadata.gz: 6c77b3cfa7c43568ea7791ab092681b4849013a52736c6a86b58520dfc65ebbd
+  data.tar.gz: 05fa38afe44718cf69416dbc3dc54d188c5089e82f9ebfa7bdfca38171dc14a6
 SHA512:
-  metadata.gz: 152cd53fb92b3e3912acff22748bc17eea6d64523c9759aa6f31dc84e3c16f715a55fd506f9f07e85e412ff9e6091c0b01d06b2411806ef6524cb98dfaffb4da
-  data.tar.gz: da08fd3f31fe6c0b1829ef08642f788c72f0726cc1a9b82c0fae06b96579f03c2dc119292d2780ae74338c9f8fb75b5862ecd69769f96964ea7f6c28899eef56
+  metadata.gz: 80126e552dd05d1837b65d5cedecef13dddb21239222e913a256719264fcf9495019d78b617d76ca994598af5ff94d14f8ed017ffa0cd60bbb34d40747cf46ab
+  data.tar.gz: 63d1884eac87f5f04f898fb0fc317fda3bd95423390a0604587c91ee63208de275b027061ececdad3be79994ede65456b7c87dba4206a671613e1cc6b4f9662e

data/README.md

@@ -80,7 +80,40 @@ value :hostname, default: 'localhost'
 
 All available options are:
 
-| name      | description                                                                                                                                        |
-|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------|
-| default   | Sets a default value for the field, if no configuration could be found. If this option is not set, getting an unset field will raise an exception. |
-| format    | Sets the format of the field. If this option is not set, the field will be formatted as string.                                                    |
+| name        | description                                                                                                                                        |
+|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
+| default     | Sets a default value for the field, if no configuration could be found. If this option is not set, getting an unset field will raise an exception. |
+| format      | Sets the format of the field. If this option is not set, the field will be formatted as string.                                                    |
+| description | A free-form text description of the field. Optional. Used for documentation generation.                                                           |
+| example     | A free-form example value for the field. Optional. Used for documentation generation.                                                             |
+| no_docs     | When set to `true`, excludes the field from documentation generation.                                                                             |
+
+The `description`, `example`, and `no_docs` options are also accepted on `group`. When `no_docs: true` is set on a group, the entire group and all its nested values are excluded from documentation.
+
+```ruby
+group :smtp, description: 'SMTP server settings' do
+  value :hostname, description: 'The SMTP server hostname', example: 'smtp.example.com'
+  value :port, format: :integer, description: 'The SMTP server port', example: '587'
+  value :password, no_docs: true
+end
+```
+
+#### Generating Documentation
+
+`SmartConfig::Markdown` renders a Markdown table documenting all values in a config module, including their descriptions, examples, defaults, and formats:
+
+```ruby
+puts SmartConfig::Markdown.new(Config).render
+```
+
+Output:
+
+```
+| Key            | Description              | Example          | Default | Format  |
+|----------------|--------------------------|------------------|---------|---------|
+| app_name       |                          |                  | My App  | string  |
+| smtp.hostname  | The SMTP server hostname | smtp.example.com |         | string  |
+| smtp.port      | The SMTP server port     | 587              |         | integer |
+```
+
+Values from nested groups are listed with their full dotted key path. Groups themselves are not rendered as rows. Values and groups with `no_docs: true` are omitted entirely.

data/lib/smart_config/markdown.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module SmartConfig
+  #
+  # Generates a markdown table documenting all config values in a SmartConfig module.
+  #
+  class Markdown
+    def initialize(config)
+      @config = config
+    end
+
+    def render
+      rows = collect_entries(@config, [])
+      return '' if rows.empty?
+
+      lines = []
+      lines << '| Key | Description | Example | Default | Format |'
+      lines << '|-----|-------------|---------|---------|--------|'
+      rows.each do |row|
+        cells = [row[:path], row[:description], row[:example], row[:default], row[:format]]
+        lines << "| #{cells.map { |c| escape(c) }.join(' | ')} |"
+      end
+      lines.join("\n")
+    end
+
+    private
+
+    def escape(value)
+      value.to_s.gsub('|', '\|')
+    end
+
+    def collect_entries(config, prefix)
+      raw = config.instance_variable_get(:@config) || {}
+      raw.flat_map do |key, entry|
+        next [] if entry[:no_docs]
+
+        next_prefix = prefix + [key.to_s]
+        if entry.key?(:group)
+          collect_entries(entry[:group], next_prefix)
+        else
+          [entry_for(entry, next_prefix)]
+        end
+      end
+    end
+
+    def entry_for(entry, prefix)
+      {
+        path: prefix.join('.'),
+        description: entry.fetch(:description, ''),
+        example: entry.fetch(:example, ''),
+        default: entry.key?(:default) ? entry[:default].to_s : '',
+        format: entry[:format].to_s
+      }
+    end
+  end
+end

data/lib/smart_config/values.rb

@@ -13,15 +13,18 @@ module SmartConfig
       @config ||= {}
       key = name.to_sym
       config = opts.reduce({}, :merge)
-      config[:formatter] = SmartConfig::Formatters.find(config.fetch(:format, :string))
+      config[:format] = config.fetch(:format, :string)
+      config[:formatter] = SmartConfig::Formatters.find(config[:format])
       @config[key] = config
       define_singleton_method(name) { format_value(key, get_value(key)) }
     end
 
-    def group(name, &)
+    def group(name, *opts, &)
       @config ||= {}
       key = name.to_sym
+      config = opts.reduce({}, :merge)
       @config[key] ||= {}
+      @config[key].merge!(config)
       @config[key][:group] = SmartConfig::Group.new([namespace, name].compact.flatten, method(:walker), &)
       define_singleton_method(name) { get_value(key) }
     end
@@ -30,6 +33,14 @@ module SmartConfig
       (@config || {}).keys
     end
 
+    def description_for(name)
+      (@config || {})[name.to_sym]&.fetch(:description, '') || ''
+    end
+
+    def example_for(name)
+      (@config || {})[name.to_sym]&.fetch(:example, '') || ''
+    end
+
     def get_value(name)
       return @config[name][:group] if @config[name].key?(:group)
 

data/lib/smart_config/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SmartConfig
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

data/lib/smart_config.rb

@@ -12,4 +12,5 @@ require 'smart_config/walker'
 require 'smart_config/values'
 require 'smart_config/group'
 require 'smart_config/config'
+require 'smart_config/markdown'
 require 'smart_config/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smart_config
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Damien MATHIEU
@@ -27,6 +27,7 @@ files:
 - lib/smart_config/formatters/integer.rb
 - lib/smart_config/formatters/string.rb
 - lib/smart_config/group.rb
+- lib/smart_config/markdown.rb
 - lib/smart_config/values.rb
 - lib/smart_config/version.rb
 - lib/smart_config/walker.rb
@@ -49,7 +50,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A DLS for reading and accessing static configuration
 test_files: []