From 9cc4f9585ba5837433abb5a6a90f5172aa4a3ac4 Mon Sep 17 00:00:00 2001 From: Jeremy Prevost Date: Thu, 27 Jun 2024 17:16:30 -0400 Subject: [PATCH] Adds yard and makefile with development commands - adds makefile with useful development commands - adds `yard` gem and documentation on how to run the local server `yard` is not perfect, but the value add is enough to include it at this time while we consider if this is a tool we want to use (either as-is or with modified templates) https://mitlibraries.atlassian.net/browse/TCO-36 --- .gitignore | 1 + .yardopts | 1 + Gemfile | 1 + Gemfile.lock | 2 ++ Makefile | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 13 +++++++++++++ 6 files changed, 66 insertions(+) create mode 100644 .yardopts create mode 100644 Makefile diff --git a/.gitignore b/.gitignore index 8464fc5..b046838 100644 --- a/.gitignore +++ b/.gitignore @@ -41,3 +41,4 @@ .DS_Store .vscode/ +.yardoc diff --git a/.yardopts b/.yardopts new file mode 100644 index 0000000..65a9e3d --- /dev/null +++ b/.yardopts @@ -0,0 +1 @@ +--no-private --protected app/**/*.rb - docs/**/*.md diff --git a/Gemfile b/Gemfile index f07d14b..c07aed4 100644 --- a/Gemfile +++ b/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 diff --git a/Gemfile.lock b/Gemfile.lock index 30122ad..97a64da 100644 --- a/Gemfile.lock +++ b/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 diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..050945f --- /dev/null +++ b/Makefile @@ -0,0 +1,48 @@ +.PHONY: test + +help: # display Makefile commands + @awk 'BEGIN { FS = ":.*#"; print "Usage: make \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! diff --git a/README.md b/README.md index 3fcdbe3..6279f83 100644 --- a/README.md +++ b/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)