SleepingKingStudios::Docs

Tools for generating a versioned documentation site from YARD docs.

Read The Documentation

SleepingKingStudios::Yard is tested against Ruby (MRI) 3.2 through 4.0.

Documentation is generated using YARD, and can be generated locally using the yard gem. Online documentation for current and previous versions is available at sleepingkingstudios.com.

Copyright (c) 2022-2025 Rob Smith

SleepingKingStudios::Docs is released under the MIT License.

The canonical repository for this gem is located at https://github.com/sleepingkingstudios/sleeping_king_studios-docs.

To report a bug or submit a feature request, please use the Issue Tracker.

To contribute code, please fork the repository, make the desired updates, and then provide a Pull Request. Pull requests must include appropriate tests for consideration, and all code must be properly formatted.

Please note that the SleepingKingStudios::Docs project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Add the docs dependencies to your Gemfile:

group :docs do
  gem 'jekyll'
  gem 'sleeping_king_studios-docs'
  gem 'webrick'
  gem 'yard',  require: false
end

You may also want to consider adding a Jekyll theme and/or a Markdown parser (Kramdown is recommended).

Generate or update your tasks.thor file:

# frozen_string_literal: true

require 'cuprum/cli/integrations/thor/registry'

registry = Cuprum::Cli::Integrations::Thor::Registry.new

require 'sleeping_king_studios/docs/jekyll'

# Docs Commands
registry.register SleepingKingStudios::Docs::Jekyll.commands

# Installation Commands (Creating or Updating Projects)
registry.register SleepingKingStudios::Docs::Jekyll.install_commands

Use the installation script to quickly install the Jekyll application:

bundle exec thor docs:jekyll:install

You can also install a GitHub pages workflow to automatically deploy to GitHub Pages. Make sure that Pages is configured for your repository to deploy from a GitHub action.

bundle exec thor docs:jekyll:install_workflow

Use the Thor CLI to generate and update the reference documentation for your project.

The docs:jekyll:generate task will generate the documentation files for each Ruby file in your project.

bundle exec thor docs:jekyll:generate

The docs:jekyll:update task will generate and update the documentation files for each Ruby file in your project. It will update any existing documentation files and remove old files that no longer correspond to objects or methods in the code.

bundle exec thor docs:jekyll:update

You can generate reference docs and copy non-release documentation into the newly created version scope using the document_version command. This is recommended for each major and minor release; patch-level changes may or may not need to be documented depending on the degree of change.

bundle exec thor docs:jekyll:document_version "1.2.3"

You can also pass a --version flag to the docs:jekyll:generate or docs:jekyll:update tasks, indicating that the generated documentation is for a specific version of the software.

bundle exec thor docs:jekyll:generate --version="1.2.3"