sleeping_king_studios-docs 0.1.0

data/lib/sleeping_king_studios/docs/tasks/generate.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/commands/generate'
+require 'sleeping_king_studios/docs/tasks'
+require 'sleeping_king_studios/docs/tasks/base'
+
+module SleepingKingStudios::Docs::Tasks
+  # CLI task for generating documentation files.
+  class Generate < SleepingKingStudios::Docs::Tasks::Base
+    namespace 'docs'
+
+    desc 'generate', 'Generates documentation files for the project'
+    option 'version',
+      type:    :string,
+      desc:    'The code version for the generated documentation',
+      default: nil
+    option 'docs_path',
+      desc:    'The relative path to the docs folder',
+      default: './docs'
+    option 'dry_run',
+      type:    :boolean,
+      default: false,
+      desc:    'If true, does not make any changes to the filesystem'
+    option 'force',
+      type:    :boolean,
+      default: false,
+      desc:    'If true, overwrites any existing files'
+    option 'verbose',
+      type:    :boolean,
+      default: true,
+      desc:    'if true, prints status messages to STDOUT'
+    # Generates documentation files for the project.
+    def generate
+      SleepingKingStudios::Docs::Commands::Generate
+        .new(**tools.hash_tools.symbolize_keys(options))
+        .call
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/tasks/installation/install_jekyll.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/commands/installation/install_jekyll'
+require 'sleeping_king_studios/docs/tasks/base'
+require 'sleeping_king_studios/docs/tasks/installation'
+
+module SleepingKingStudios::Docs::Tasks::Installation
+  # CLI task for installing the Jekyll application.
+  class InstallJekyll < SleepingKingStudios::Docs::Tasks::Base
+    namespace 'docs'
+
+    desc 'install', 'Install the Jekyll application'
+    option 'description',
+      type:     :string,
+      optional: true,
+      desc:     'A short description of the documented library.'
+    option 'docs_path',
+      desc:    'The relative path to the docs folder',
+      default: './docs'
+    option 'dry_run',
+      type:    :boolean,
+      default: false,
+      desc:    'If true, does not make any changes to the filesystem'
+    option 'name',
+      type:     :string,
+      optional: true,
+      desc:     'The name of the documented library.'
+    option 'repository',
+      type:     :string,
+      optional: true,
+      desc:     'The URL of the library repository.'
+    option 'root_path',
+      type:     :string,
+      optional: true,
+      desc:     'The root path for the library'
+    option 'verbose',
+      type:    :boolean,
+      default: true,
+      desc:    'if true, prints status messages to STDOUT'
+    # Install the Jekyll application
+    def install
+      SleepingKingStudios::Docs::Commands::Installation::InstallJekyll
+        .new(**constructor_options)
+        .call(**command_options)
+    end
+
+    private
+
+    def command_options
+      %w[docs_path root_path]
+        .reduce({}) do |hsh, key|
+          next hsh unless options.key?(key)
+
+          hsh.merge(key.intern => options[key])
+        end
+    end
+
+    def constructor_options
+      %w[description dry_run name repository verbose]
+        .reduce({}) do |hsh, key|
+          next hsh unless options.key?(key)
+
+          hsh.merge(key.intern => options[key])
+        end
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/tasks/installation/install_templates.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/commands/installation/install_templates'
+require 'sleeping_king_studios/docs/tasks/base'
+require 'sleeping_king_studios/docs/tasks/installation'
+
+module SleepingKingStudios::Docs::Tasks::Installation
+  # CLI task for installing Jekyll templates for a library.
+  class InstallTemplates < SleepingKingStudios::Docs::Tasks::Base
+    namespace 'docs:install'
+
+    desc 'templates', 'Installs or updates the Jekyll templates'
+    option 'docs_path',
+      desc:    'The relative path to the docs folder',
+      default: './docs'
+    option 'dry_run',
+      type:    :boolean,
+      default: false,
+      desc:    'If true, does not make any changes to the filesystem'
+    option 'force',
+      type:    :boolean,
+      default: false,
+      desc:    'If true, overwrites existing template files'
+    option 'verbose',
+      type:    :boolean,
+      default: true,
+      desc:    'if true, prints status messages to STDOUT'
+    # Installs or updates the Jekyll templates
+    def templates
+      SleepingKingStudios::Docs::Commands::Installation::InstallTemplates
+        .new(
+          dry_run: options['dry_run'],
+          force:   options['force'],
+          verbose: options['verbose']
+        )
+        .call(docs_path: options['docs_path'])
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/tasks/installation/install_workflow.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/commands/installation/install_workflow'
+require 'sleeping_king_studios/docs/tasks/base'
+require 'sleeping_king_studios/docs/tasks/installation'
+
+module SleepingKingStudios::Docs::Tasks::Installation
+  # CLI task for installing the GitHub pages CI workflow.
+  class InstallWorkflow < SleepingKingStudios::Docs::Tasks::Base
+    namespace 'docs:install'
+
+    desc 'workflow', 'Installs the GitHub pages CI workflow'
+    option 'dry_run',
+      type:    :boolean,
+      default: false,
+      desc:    'If true, does not make any changes to the filesystem'
+    option 'force',
+      type:    :boolean,
+      default: false,
+      desc:    'If true, overwrites existing template files'
+    option 'root_path',
+      type:     :string,
+      optional: true,
+      desc:     'The root path for the library'
+    option 'verbose',
+      type:    :boolean,
+      default: true,
+      desc:    'if true, prints status messages to STDOUT'
+    # Installs the GitHub pages CI workflow.
+    def workflow
+      SleepingKingStudios::Docs::Commands::Installation::InstallWorkflow
+        .new(**constructor_options)
+        .call(**command_options)
+    end
+
+    private
+
+    def command_options
+      return {} unless options.key?('root_path')
+
+      { root_path: options['root_path'] }
+    end
+
+    def constructor_options
+      %w[dry_run force verbose]
+        .reduce({}) do |hsh, key|
+          next hsh unless options.key?(key)
+
+          hsh.merge(key.intern => options[key])
+        end
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/tasks/installation.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/tasks'
+
+module SleepingKingStudios::Docs::Tasks
+  # Namespace for CLI tasks for installing and updating the Jekyll docs.
+  module Installation; end
+end

data/lib/sleeping_king_studios/docs/tasks/update.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/commands/generate'
+require 'sleeping_king_studios/docs/tasks'
+require 'sleeping_king_studios/docs/tasks/base'
+
+module SleepingKingStudios::Docs::Tasks
+  # CLI task for updating documentation files.
+  class Update < SleepingKingStudios::Docs::Tasks::Base
+    namespace 'docs'
+
+    desc 'update', 'Updates the documentation files for the project'
+    option 'version',
+      type:    :string,
+      desc:    'The code version for the generated documentation',
+      default: nil
+    option 'docs_path',
+      desc:    'The relative path to the docs folder',
+      default: './docs'
+    option 'dry_run',
+      type:    :boolean,
+      default: false,
+      desc:    'If true, does not make any changes to the filesystem'
+    option 'verbose',
+      type:    :boolean,
+      default: true,
+      desc:    'if true, prints status messages to STDOUT'
+    # Updates the documentation files for the project.
+    def update
+      SleepingKingStudios::Docs::Commands::Generate
+        .new(force: true, **tools.hash_tools.symbolize_keys(options))
+        .call
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/tasks.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs'
+
+module SleepingKingStudios::Docs
+  # Namespace for CLI tasks, powered by Thor.
+  module Tasks; end
+end
+
+require 'sleeping_king_studios/docs/tasks/generate'
+require 'sleeping_king_studios/docs/tasks/installation/install_jekyll'
+require 'sleeping_king_studios/docs/tasks/installation/install_templates'
+require 'sleeping_king_studios/docs/tasks/installation/install_workflow'
+require 'sleeping_king_studios/docs/tasks/update'

data/lib/sleeping_king_studios/docs/templates/config.yml.erb

@@ -0,0 +1,22 @@
+---
+collections:
+  classes:
+    output: false
+  constants:
+    output: false
+  methods:
+    output: false
+  modules:
+    output: false
+  namespaces:
+    output: false
+defaults:
+- scope:
+    path: ''
+    type: 'pages'
+  values:
+    encoding: 'utf-8'
+    layout: 'default'
+    title: '<%= name %>'
+description: |
+  <%= description %>

data/lib/sleeping_king_studios/docs/templates/deploy-pages.yml.erb

@@ -0,0 +1,67 @@
+name: Deploy Jekyll site to Pages
+
+on:
+  push: {}
+  pull_request: {}
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '<%= ruby_version %>'
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
+
+      - name: Build with Jekyll
+        # Outputs to the './_site' directory by default
+        run: |
+          bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" --source=docs --destination=docs/_site
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v3
+
+        with:
+          path: docs/_site
+
+        if: ${{ github.ref == 'refs/heads/main' }}
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    needs: build
+
+    if: ${{ github.ref == 'refs/heads/main' }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/lib/sleeping_king_studios/docs/templates/includes/breadcrumbs.md

@@ -0,0 +1,7 @@
+
+---
+
+Back to
+{% for breadcrumb in page.breadcrumbs -%}
+[{{ breadcrumb.name }}]({{breadcrumb.path}}){% unless forloop.last %} | {% endunless %}
+{% endfor %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/attribute.md

@@ -0,0 +1,23 @@
+{% assign method = site.methods | where: "data_path", include.attribute.path | where: "version", page.version | first %}
+{% capture prefix %}{{ include.type }}-attribute{% endcapture %}
+{% capture heading_id %}{{ prefix }}-{{ method.slug | replace: "=", "--equals" }}{% endcapture %}
+
+{% include reference/attributes/heading.md attribute=include.attribute heading_id=heading_id method=method type=include.type %}
+
+{% include reference/methods/aliases.md method=method %}
+
+{% include reference/methods/inherited.md inherited=include.inherited method=method %}
+
+{% include reference/methods/overview.md method=method heading_id=heading_id prefix=prefix %}
+
+{% include reference/methods/overloads.md heading_id=heading_id method=method %}
+
+{% include reference/methods/parameters.md heading_id=heading_id method=method %}
+
+{% include reference/methods/yields.md heading_id=heading_id method=method %}
+
+{% include reference/methods/returns.md heading_id=heading_id method=method %}
+
+{% include reference/methods/raises.md heading_id=heading_id method=method %}
+
+{% include reference/methods/post_overview.md heading_id=heading_id method=method %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/attributes/heading.md

@@ -0,0 +1,15 @@
+{% capture char %}{% if include.type == "class" %}.{% else %}#{% endif %}{% endcapture %}
+{% capture access %}{% if include.attribute.read and include.attribute.write %}{% elsif include.attribute.read %} <small>(readonly)</small>{% else %} <small>(writeonly)</small>{% endif %}{% endcapture %}
+{% capture abstract %}{% if include.method.metadata.abstract %} <small>(abstract)</small>{% endif %}{% endcapture %}
+{% capture deprecated %}{% if include.method.metadata.deprecated %} <small>(deprecated)</small>{% endif %}{% endcapture %}
+
+<h3>
+  {% if include.method.overloads.size > 0 %}
+  {% for overload in include.method.overloads %}
+  <code>{{ char }}{{ overload.signature }} => {% include reference/methods/return_types.md method=overload %}{{ access }}</code>{% unless forloop.last %}<br />{% endunless %}
+  {% endfor %}
+  {%- else -%}
+  <code>{{ char }}{{ include.method.signature }} => {% include reference/methods/return_types.md method=include.method %}{{ access }}{{ abstract }}{{ deprecated }}</code>
+  {% endif %}
+</h3>
+{: #{{ include.heading_id }} }

data/lib/sleeping_king_studios/docs/templates/includes/reference/class.md

@@ -0,0 +1,27 @@
+{% assign definition = site.classes | where: "data_path", page.data_path | where: "version", page.version | first %}
+
+# Class: {{ definition.name }}
+
+{% include reference/definitions/details.md definition=definition %}
+
+{% include reference/definitions/table-of-contents.md definition=definition %}
+
+{% include reference/definitions/overview.md definition=definition %}
+
+{% include reference/definitions/subclasses.md definition=definition %}
+
+{% include reference/definitions/definitions.md definition=definition %}
+
+{% include reference/definitions/constants.md definition=definition %}
+
+{% include reference/definitions/class_attributes.md definition=definition %}
+
+{% include reference/definitions/class_methods.md definition=definition %}
+
+{% include reference/definitions/constructor.md definition=definition %}
+
+{% include reference/definitions/instance_attributes.md definition=definition %}
+
+{% include reference/definitions/instance_methods.md definition=definition constructor=definition.constructor %}
+
+{% include reference/definitions/breadcrumbs.md definition=definition %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/constant.md

@@ -0,0 +1,8 @@
+{% assign const = site.constants | where: "data_path", include.constant.path | where: "version", page.version | first %}
+{% capture heading_id %}constant-{{ const.slug }}{% endcapture %}
+
+{% include reference/constants/heading.md constant=const heading_id=heading_id %}
+
+{% include reference/constants/inherited.md constant=const inherited=include.inherited %}
+
+{% include reference/constants/overview.md constant=const heading_id=heading_id %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/constants/heading.md

@@ -0,0 +1,6 @@
+<h3>
+  <code>{{ constant.name }}</code>
+</h3>
+{: #{{ heading_id }} }
+
+<span class="constant-value" style="margin-left: 1rem;">= <code>{{ include.constant.value }}</code></span>

data/lib/sleeping_king_studios/docs/templates/includes/reference/constants/inherited.md

@@ -0,0 +1,4 @@
+{% if include.inherited %}
+Inherited From
+: {% include reference/parent_link.md parent_path=include.constant.parent_path %}
+{% endif %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/constants/overview.md

@@ -0,0 +1,60 @@
+{% if include.constant.metadata.todos.size > 0 %}
+{% for todo in include.constant.metadata.todos %}
+> **Todo:** {{ todo }}
+{% endfor %}
+{% endif %}
+
+{% if include.constant.metadata.notes.size > 0 %}
+{% for note in include.constant.metadata.notes %}
+> *Note:* {{ note }}
+{% endfor %}
+{% endif %}
+
+{% if include.constant.short_description %}
+{{ include.constant.short_description }}
+{% endif %}
+
+{% if include.constant.description %}
+{{ include.constant.description }}
+{% endif %}
+
+{% if include.constant.metadata.examples.size > 0 %}
+#### Examples
+{: #{{ include.heading_id }}--examples }
+{% for example in include.constant.metadata.examples %}
+{% if example.name.size > 0 %}**{{ example.name }}**{% endif %}
+{% highlight ruby %}{{ example.text }}{% endhighlight %}
+{% endfor %}
+{% endif %}
+
+{% if include.constant.metadata.see.size > 0 %}
+#### See Also
+{: #{{ include.heading_id }}--see-also }
+{% for see in include.constant.metadata.see %}
+- {% include reference/see_link.md see=see -%}
+{% endfor %}
+{% endif %}
+
+{% if include.constant.metadata.authors.size > 0 %}
+#### Author{% if include.constant.metadata.authors.size > 1 %}s{% endif %}
+{: #{{ include.heading_id }}--authors }
+{% for author in include.constant.metadata.authors %}
+- {{ author -}}
+{% endfor %}
+{% endif %}
+
+{% if include.constant.metadata.since.size > 0 %}
+#### Since
+{: #{{ include.heading_id }}--since }
+{% for since in include.constant.metadata.since %}
+- {{ since -}}
+{% endfor %}
+{% endif %}
+
+{% if include.constant.metadata.versions.size > 0 %}
+#### Version{% if include.constant.metadata.versions.size > 1 %}s{% endif %}
+{: #{{ include.heading_id }}--versions }
+{% for version in include.constant.metadata.versions %}
+- {{ version -}}
+{% endfor %}
+{% endif %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/definitions/breadcrumbs.md

@@ -0,0 +1,21 @@
+{% capture breadcrumbs %}
+{% if include.definition.parent_path.size > 0 %}
+{% assign parent_definition = site.classes | where: "data_path", include.definition.parent_path | where: "version", page.version | first %}
+{%- unless parent_definition %}{% assign parent_definition = site.modules | where: "data_path", include.definition.parent_path | where: "version", page.version | first %}{% endunless %}
+{%- include reference/definitions/breadcrumbs.md definition=parent_definition %} | {% include reference/parent_link.md parent_path=include.definition.parent_path -%}
+{%- else %}
+
+---
+
+Back to
+[Documentation]({{site.baseurl}}/) |
+{%- if page.version == "*" %}
+[Reference]({{site.baseurl}}/reference)
+{%- else %}
+[Versions]({{site.baseurl}}/versions) |
+[{{ page.version }}]({{site.baseurl}}/versions/{{page.version}}) |
+[Reference]({{site.baseurl}}/versions/{{page.version}}/reference)
+{% endif %}
+{%- endif %}
+{% endcapture %}
+{{ breadcrumbs | strip }}

data/lib/sleeping_king_studios/docs/templates/includes/reference/definitions/class_attributes.md

@@ -0,0 +1,9 @@
+{% if include.definition.class_attributes.size > 0 %}
+## Class Attributes
+
+{% for class_attribute in include.definition.class_attributes %}
+{% include reference/attribute.md attribute=class_attribute type="class" inherited=class_attribute.inherited %}
+{% endfor %}
+
+[Back To Top](#)
+{% endif %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/definitions/class_methods.md

@@ -0,0 +1,9 @@
+{% if include.definition.class_methods.size > 0 %}
+## Class Methods
+
+{% for class_method in include.definition.class_methods %}
+{% include reference/method.md name=class_method.name path=class_method.path type="class" inherited=class_method.inherited %}
+{% endfor %}
+
+[Back To Top](#)
+{% endif %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/definitions/constants.md

@@ -0,0 +1,9 @@
+{% if include.definition.constants.size > 0 %}
+## Constants
+
+{% for constant in include.definition.constants %}
+{% include reference/constant.md constant=constant inherited=constant.inherited %}
+{% endfor %}
+
+[Back To Top](#)
+{% endif %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/definitions/constructor.md

@@ -0,0 +1,12 @@
+{% if include.definition.constructor %}
+{% for instance_method in include.definition.instance_methods %}
+{% if instance_method.constructor %}
+{% assign path=instance_method.path %}
+{% assign inherited=instance_method.inherited %}
+{% endif %}
+{% endfor %}
+## Constructor
+{% include reference/method.md name="initialize" inherited=inherited path=path type="instance" %}
+
+[Back To Top](#)
+{% endif %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/definitions/definitions.md

@@ -0,0 +1,23 @@
+{% if include.definition.defined_classes.size > 0 or include.definition.defined_modules.size > 0 %}
+## Defined Under Namespace
+
+{% if include.definition.defined_classes.size > 0 %}
+Classes
+: {% for defined_class in include.definition.defined_classes -%}
+  {% capture path %}{{ include.definition.data_path }}/{{ defined_class.slug }}{% endcapture %}
+  {% include reference/reference_link.md label=defined_class.name path=path -%}
+  {% unless forloop.last %}, {% endunless %}
+  {%- endfor %}
+{% endif %}
+
+{% if include.definition.defined_modules.size > 0 %}
+Modules
+: {% for defined_module in include.definition.defined_modules -%}
+  {% capture path %}{{ include.definition.data_path }}/{{ defined_module.slug }}{% endcapture %}
+  {% include reference/reference_link.md label=defined_module.name path=path -%}
+  {% unless forloop.last %}, {% endunless %}
+  {%- endfor %}
+{% endif %}
+
+[Back To Top](#)
+{% endif %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/definitions/details.md

@@ -0,0 +1,34 @@
+{% if include.definition.parent_path.size > 0 %}
+Parent Namespace
+: {% include reference/parent_link.md parent_path=include.definition.parent_path -%}
+{% endif %}
+
+{% if include.definition.inherited_classes.size > 0 %}
+Inherited Classes
+: {% for inherited_class in include.definition.inherited_classes -%}
+  {% include reference/reference_link.md label=inherited_class.name path=inherited_class.path %}
+  >
+  {% endfor -%}
+  Object
+{% endif %}
+
+{% if include.definition.extended_modules.size > 0 %}
+Extended Modules
+: {% for extended_module in include.definition.extended_modules -%}
+  {% include reference/reference_link.md label=extended_module.name path=extended_module.path -%}
+  {% unless forloop.last %}, {% endunless %}
+  {%- endfor %}
+{% endif %}
+
+{% if include.definition.included_modules.size > 0 %}
+Included Modules
+: {% for included_module in include.definition.included_modules -%}
+  {% include reference/reference_link.md label=included_module.name path=included_module.path -%}
+  {% unless forloop.last %}, {% endunless %}
+  {%- endfor %}
+{% endif %}
+
+{% if include.definition.files.size > 0 %}
+Defined In
+: {{ include.definition.files | first }}
+{% endif %}

data/lib/sleeping_king_studios/docs/templates/includes/reference/definitions/instance_attributes.md

@@ -0,0 +1,9 @@
+{% if include.definition.instance_attributes.size > 0 %}
+## Instance Attributes
+
+{% for instance_attribute in include.definition.instance_attributes %}
+{% include reference/attribute.md attribute=instance_attribute write=instance_attribute.write type="instance" inherited=instance_attribute.inherited %}
+{% endfor %}
+
+[Back To Top](#)
+{% endif %}