From c10b847e818fc3c5d2a634ea3c2fcf94ae6a95aa Mon Sep 17 00:00:00 2001
From: Bill Niblock <azulien@protonmail.com>
Date: Sun, 7 Mar 2021 16:57:27 -0500
Subject: [PATCH] Add Yard, and begin some documentation
Use Yard to generate documentation. Included in the `.yardopts` file is
configuration to also publish the markdown files in the `wiki/`
directory.
wiki/
- addons.md: Information on writing new addons.
- database.md: Information on using the database and migrations
db/migrate/*: Rename in accordance with documentation
Rakefile: Add the Yard Rake tasks
---
.yardopts | 5 ++
Gemfile | 2 +
Rakefile | 26 +++++--
db/migrate/0001_create_general.rb | 15 ++++
...ands.rb => 0100_create_custom_commands.rb} | 2 +-
wiki/addons.md | 19 +++++
wiki/database.md | 78 +++++++++++++++++++
7 files changed, 140 insertions(+), 7 deletions(-)
create mode 100644 .yardopts
create mode 100644 db/migrate/0001_create_general.rb
rename db/migrate/{001_create_custom_commands.rb => 0100_create_custom_commands.rb} (79%)
create mode 100644 wiki/addons.md
create mode 100644 wiki/database.md
diff --git a/.yardopts b/.yardopts
new file mode 100644
index 0000000..f84e364
--- /dev/null
+++ b/.yardopts
@@ -0,0 +1,5 @@
+--protected
+--private
+-
+wiki/database.md
+wiki/addons.md
diff --git a/Gemfile b/Gemfile
index ea691ac..670f5a7 100644
--- a/Gemfile
+++ b/Gemfile
@@ -9,3 +9,5 @@ gem "activerecord", "~> 6.1"
gem "rake", "~> 13.0"
gem "sqlite3", "~> 1.4"
+
+gem "yard", "~> 0.9.26"
diff --git a/Rakefile b/Rakefile
index 027874e..259af4a 100644
--- a/Rakefile
+++ b/Rakefile
@@ -4,7 +4,7 @@ namespace :chronicle do
require 'active_record'
require_relative 'lib/chronicle'
- db_config = YAML::load(File.open('config/database.yml'))
+ db_config = YAML::load(File.open('config/db.yml'))
ActiveRecord::Base.establish_connection(db_config)
bot_config = YAML::load(File.open('config/bot.yml'))
@@ -18,18 +18,20 @@ namespace :db do
require 'active_record'
require 'yaml'
- Dir[File.join(__dir__, 'db', 'migrate', '*.rb')].each do |file|
+ klasses = []
+ Dir[File.join(__dir__, 'db', 'migrate', '*.rb')].sort.each do |file|
require file
+ klasses << file.split('_')[1..-1].map(&:capitalize).join[0..-4]
end
task :connect do
- connection_details = YAML::load(File.open('config/database.yml'))
+ connection_details = YAML::load(File.open('config/db.yml'))
ActiveRecord::Base.establish_connection(connection_details)
end
desc "Create a new database"
task :create do
- connection_details = YAML::load(File.open('config/database.yml'))
+ connection_details = YAML::load(File.open('config/db.yml'))
if connection_details["adapter"] == 'sqlite3'
if File.exists?(connection_details["database"])
@@ -48,12 +50,24 @@ namespace :db do
desc "Run the migrations"
task :migrate => 'db:connect' do
# ActiveRecord::MigrationContext.new('db/migrate/').migrate()
- CreateCustomCommands.migrate(:up)
+ # CreateCustomCommands.migrate(:up)
+ klasses.each do |k|
+ k.constantize.public_send('migrate', :up)
+ end
end
desc "Clear the database"
task :drop => 'db:connect' do
# ActiveRecord::Migration.migrate(:down)
- CreateCustomCommands.migrate(:down)
+ # CreateCustomCommands.migrate(:down)
+ klasses.each do |k|
+ k.constantize.public_send('migrate', :down)
+ end
end
end
+
+namespace :dev do
+ require 'yard'
+
+ YARD::Rake::YardocTask.new
+end
diff --git a/db/migrate/0001_create_general.rb b/db/migrate/0001_create_general.rb
new file mode 100644
index 0000000..29e6960
--- /dev/null
+++ b/db/migrate/0001_create_general.rb
@@ -0,0 +1,15 @@
+class CreateGeneral < ActiveRecord::Migration[6.1]
+ def up
+ create_table :general do |table|
+ table.string :roomid
+ table.string :protocol
+ table.string :prefix_char
+ table.integer :permission_level
+ table.timestamps
+ end
+ end
+
+ def down
+ drop_table :general
+ end
+end
diff --git a/db/migrate/001_create_custom_commands.rb b/db/migrate/0100_create_custom_commands.rb
similarity index 79%
rename from db/migrate/001_create_custom_commands.rb
rename to db/migrate/0100_create_custom_commands.rb
index f5b8b27..5734964 100644
--- a/db/migrate/001_create_custom_commands.rb
+++ b/db/migrate/0100_create_custom_commands.rb
@@ -1,4 +1,4 @@
-class CreateCustomCommands < ActiveRecord::Migration[5.2]
+class CreateCustomCommands < ActiveRecord::Migration[6.1]
def up
create_table :custom_commands do |table|
table.string :roomid
diff --git a/wiki/addons.md b/wiki/addons.md
new file mode 100644
index 0000000..4fb8f73
--- /dev/null
+++ b/wiki/addons.md
@@ -0,0 +1,19 @@
+# @markup markdown
+# @title Add-Ons
+
+# Chronicle Add-ons
+
+Add-ons represent functionality that may not be universally enabled or desired
+by default. Provided examples include a dice roller, a custom command handler,
+and some simple games.
+
+Writing an add-on for Chronicle is relatively straight forward, and being
+refined as I develop it more.
+
+## Creating an Add-on
+
+### General requirements
+
+### Protocol requirements
+
+### Database requirements
diff --git a/wiki/database.md b/wiki/database.md
new file mode 100644
index 0000000..af79d62
--- /dev/null
+++ b/wiki/database.md
@@ -0,0 +1,78 @@
+# @markup markdown
+# @title Database
+
+# Chronicle Database
+
+Chronicle leverages a database for persistent storage. It uses ActiveRecord for
+interfacing with the supported database types, performing migrations, and
+interacting with models.
+
+## Supported Databases
+
+### Currently Supported:
+
+- SQLite
+
+### Planned Support:
+
+- PostgreSQL
+- MySQL
+- MariaDB
+
+## Creating the Database
+
+There's a Rake task for creating the database according to ActiveRecord: `rake
+db:create`. For configuration, check out `config/db.yml`. The default
+configuration will create a SQLite3 database at `db/chronicle-bot.db`.
+
+## Working With the Migrations
+
+ActiveRecord migrations are database-agnostic schema alterations, stored as
+code. This allows Chronicle to support multiple different database
+architectures, without having to write custom code for each one. Migrations can
+represent changes tied to new versions, or additional database configuration
+tied to an add-on or protocol, for example.
+
+To apply the migrations, use the Rake task `rake db:migrate`.
+
+To roll-back the migrations, use the Rake task `rake db:down`.
+
+### Provided Migrations
+
+By default, Chronicle includes a migration for setting up the "general" table,
+which provides details around the bot itself.
+
+It also includes a migration for the Custom Commands add-on, which creates a
+table for storing the commands and responses, along with the room ID the command
+was created in.
+
+Each of these migrations include a "roll-back" solution, which simply drops the
+corresponding tables.
+
+### Writing Additional Migrations
+
+The most important thing when creating new migrations is to follow the naming
+convention:
+
+```
+ XXXX_name_of_migration.rb
+```
+
+The Rake tasks for working with migrations will look at every file in the
+`db/migrate/` directory, and sort them. It will `require` those files, and then
+compile a list of the classes within those files according to specific logic: it
+takes the file name, drops the numbers at the beginning, and converts the file
+name from snake case and to camel case, dropping the file extension. For example,
+"0000_create_general.rb" will be processed to the class named "CreateGeneral",
+which will be added to a list. The Rake task will then go through each the list
+of all classes and run the "migrate" method of each class, passing it "up" if
+migrations are being applied, or "down" if migrations are being rolled-back.
+
+Generally speaking, the number for the migration is mostly important for sorting
+order. However, a simple naming convention can help distinguish between types of
+migrations, by changing the 2nd-position digit:
+
+- For migrations tied to Chronicle functionality, use `00XX`.
+- For migrations tied to addon functionality, use `01XX`.
+- For migrations tied to protocol functionality, use `02XX`.
+- For any miscellaneous migrations, use `03XX`.