Merge pull request #50 from MITLibraries/yard-and-makefile

Adds yard and makefile with development commands

.gitignore

@@ -41,3 +41,4 @@
 
 .DS_Store
 .vscode/
+.yardoc

.yardopts

@@ -0,0 +1 @@
+--no-private --protected app/**/*.rb - docs/**/*.md

Gemfile

@@ -85,6 +85,7 @@ group :development do
 
   # Add speed badges [https://github.com/MiniProfiler/rack-mini-profiler]
   # gem "rack-mini-profiler"
+  gem 'yard'
 end
 
 group :test do

Gemfile.lock

@@ -333,6 +333,7 @@ GEM
     websocket-extensions (0.1.5)
     xpath (3.2.0)
       nokogiri (~> 1.8)
+    yard (0.9.36)
     zeitwerk (2.6.16)
 
 PLATFORMS
@@ -370,6 +371,7 @@ DEPENDENCIES
   vcr
   web-console
   webmock
+  yard
 
 RUBY VERSION
    ruby 3.2.2p53

Makefile

@@ -0,0 +1,48 @@
+.PHONY: test
+
+help: # display Makefile commands
+	@awk 'BEGIN { FS = ":.*#"; print "Usage:  make <target>\n\nTargets:" } \
+  /^[-_[:alpha:]]+:.?*#/ { printf "  %-15s%s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+#######################
+# Local development commands
+#######################
+
+run: # runs server on localhost
+	bin/rails server
+
+console: # runs console
+	bin/rails console
+
+test: # Run tests
+	bin/rails test
+
+coverage: test # Run tests and open coverage report in default web browser
+	open coverage/index.html
+
+#######################
+# Documentation commands
+#######################
+
+annotate: # update Rails models documentation header
+	bundle exec annotate --models
+
+docserver: # runs local documentation server
+	rm -rf .yardoc # Clears cache as it's sketchy af
+	yard server --reload
+
+#######################
+# Dependency commands
+#######################
+
+install: # Install dependencies
+	bundle install
+
+outdated: # List outdated dependencies
+	bundle outdated
+
+####################################
+# Code quality and safety commands
+####################################
+
+# coming soon!

README.md

@@ -1,5 +1,11 @@
 # TACOS: Tool for Analyzing and Categorization Of Searchterms
 
+## Local development
+
+There is a `Makefile` that contains some useful command shortcuts for typical development tasks.
+
+To see a current list of commands, run `make help`.
+
 ## Environment Variables
 
 ### Required
@@ -16,6 +22,8 @@
 
 ## Documentation
 
+### Architecture Decisions
+
 [Architecture Decisions](docs/architecture-decisions/)
 
 ### Explanation/Overview
@@ -26,4 +34,9 @@
 
 ### Reference
 
+`make docserver` will start a `yard` server using the RDoc comments from the codebase. RDoc in this application is a work-in-progress and should improve over time. As of this writing, the index page generated contains broken links to our markdown documentation, but they "files" navigation displays them properly.
+
+> [!TIP]  
+> Prior to running `make docserver` the first time, you must install the bundled gems for this application using either `bundle install` or `make install` (they both do the same thing!).
+
 [Class Diagram](docs/reference/classes.md)