SleepingKingStudios::Docs

Tools for generating a versioned documentation site from YARD docs.

Read The Documentation

SleepingKingStudios::Yard is tested against Ruby (MRI) 3.1 through 3.4.

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

load 'sleeping_king_studios/docs/tasks.rb'

Use the installation script to quickly install the Jekyll application:

bundle exec thor docs:install --name="Orichalcum" --description="A real gem." --repository="www.example.com"

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:install:workflow

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

The docs:generate task will generate the documentation files for each Ruby file in your project. It does not update any existing files by default, so if you have made changes to existing code use the docs:update command or use the --force command line option.

bundle exec thor docs:generate

The docs:update task will generate and updates th documentation files for each Ruby file in your project. It will update any existing documentation files.

bundle exec thor docs:update

You can pass a --version flag to the docs:generate or docs:update tasks, indicating that the generated documentation is for a specific version of the software. 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:generate --version="1.2.3"

Any non-reference documentation should be copied into the newly created version scope. Make sure to update the versions/index.md file to link the new scope.