Makefile

pages_url    := https://the-ai-alliance.github.io/REPO_NAME/
docs_dir     := docs
site_dir     := ${docs_dir}/_site
clean_dirs   := ${site_dir} ${docs_dir}/.sass-cache

# Environment variables
MAKEFLAGS            = --warn-undefined-variables
MAKEFLAGS_RECURSIVE ?= # --print-directory (only useful for recursive makes...)
UNAME               ?= $(shell uname)
ARCHITECTURE        ?= $(shell uname -m)

# Override when running `make view-local` using e.g., `JEKYLL_PORT=8000 make view-local`
JEKYLL_PORT         ?= 4000

# Used for version tagging release artifacts.
GIT_HASH            ?= $(shell git show --pretty="%H" --abbrev-commit |head -1)
NOW                 ?= $(shell date +"%Y%m%d-%H%M%S")

define help_message
Quick help for this make process.

make all                # Clean and locally view the document.
make clean              # Remove built artifacts, etc.
make view-pages         # View the published GitHub pages in a browser.
make view-local         # View the pages locally (requires Jekyll).
                        # Tip: "JEKYLL_PORT=8000 make view-local" uses port 8000 instead of 4000!

Miscellaneous tasks for help, debugging, setup, etc.

make help               # Prints this output.
make print-info         # Print the current values of some make and env. variables.
make setup-jekyll       # Install Jekyll. Make sure Ruby is installed. 
                        # (Only needed for local viewing of the document.)
make run-jekyll         # Used by "view-local"; assumes everything is already built.
                        # Tip: "JEKYLL_PORT=8000 make run-jekyll" uses port 8000 instead of 4000!
endef

define missing_shell_command_error_message
is needed by ${PWD}/Makefile. Try 'make help' and look at the README.
endef

ifndef docs_dir
$(error ERROR: There is no ${docs_dir} directory!)
endif

define gem-error-message

ERROR: Did the gem command fail with a message like this?
ERROR:
ERROR: 	 "You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory."
ERROR: To run the "gem install ..." command for the MacOS default ruby installation requires "sudo".
ERROR: Instead, use Homebrew (https://brew.sh) to install ruby and make sure "/usr/local/.../bin/gem"
ERROR: is on your PATH before "user/bin/gem".
ERROR:
ERROR: Or did the gem command fail with a message like this?
ERROR:
ERROR:   Bundler found conflicting requirements for the RubyGems version:
ERROR:     In Gemfile:
ERROR:       foo-bar (>= 3.0.0) was resolved to 3.0.0, which depends on
ERROR:         RubyGems (>= 3.3.22)
ERROR:   
ERROR:     Current RubyGems version:
ERROR:       RubyGems (= 3.3.11)
ERROR:
ERROR: In this case, try "brew upgrade ruby@3.3.5" (or use whatever ruby manager
ERROR: you use) to get a newer version.
ERROR: 
ERROR: NOTE: At this time, Ruby 4.0+ aren't supported by GitHub Pages!
ERROR: If you instead see an error message like this:
ERROR: 
ERROR:   Resolving dependencies...
ERROR:   Could not find compatible versions
ERROR:   
ERROR:   Because github-pages >= 232 depends on jekyll-commonmark-ghpages = 0.5.1
ERROR:     and jekyll-commonmark-ghpages >= 0.2.0 depends on jekyll-commonmark ~> 1.4.0,
ERROR:     github-pages >= 232 requires jekyll-commonmark ~> 1.4.0.
ERROR:   And because jekyll-commonmark >= 1.4.0 depends on commonmarker ~> 0.22
ERROR:     and commonmarker >= 0.22.0, < 1.0.0.pre depends on Ruby >= 2.6, < 4.0,
ERROR:     github-pages >= 232 requires Ruby >= 2.6, < 4.0.
ERROR:   So, because Gemfile depends on github-pages ~> 232
ERROR:     and current Ruby version is = 4.0.3,
ERROR:     version solving has failed.
ERROR:
ERROR: This means you are trying to use Ruby 4.0+, which isn't supported by
ERROR: GitHub Pages! Use your Ruby management tool (eg., 'chruby', Homebrew, ...)
ERROR: to install a 3.X version, e.g., 3.3.5. Tools like 'chruby' let you install
ERROR: and use multiple versions of Ruby.

endef

define bundle-error-message

ERROR: Did the bundle command fail with a message like this?
ERROR:
ERROR: 	 "/usr/local/opt/ruby/bin/bundle:25:in `load': cannot load such file -- /usr/local/lib/ruby/gems/3.1.0/gems/bundler-X.Y.Z/exe/bundle (LoadError)"
ERROR:
ERROR: Check that the /usr/local/lib/ruby/gems/3.1.0/gems/bundler-X.Y.Z directory actually exists. 
ERROR:
ERROR: If not, try running the clean-jekyll command first:
ERROR:   make clean-jekyll setup-jekyll
ERROR: Answer "y" (yes) to the prompts and ignore any warnings that you can't uninstall a "default" gem.

endef

define ruby_installation_message
See ruby-lang.org for installation instructions.

WARNING: Install the latest Ruby version 3 release. 
WARNING: Version 4 releases aren't supported by GitHub Pages.
endef

.PHONY: all view-pages view-local clean help 
.PHONY: setup-jekyll run-jekyll

all:: view-local

help::
	$(info ${help_message})
	@echo

print-info:
	@echo "GitHub Pages URL:    ${pages_url}"
	@echo "current dir:         ${PWD}"
	@echo "docs dir:            ${docs_dir}"
	@echo "site dir:            ${site_dir}"
	@echo "clean dirs:          ${clean_dirs} (deleted by 'make clean')"
	@echo
	@echo "MAKEFLAGS:           ${MAKEFLAGS}"
	@echo "MAKEFLAGS_RECURSIVE: ${MAKEFLAGS_RECURSIVE}"
	@echo "JEKYLL_PORT:         ${JEKYLL_PORT}"
	@echo "UNAME:               ${UNAME}"
	@echo "ARCHITECTURE:        ${ARCHITECTURE}"
	@echo "GIT_HASH:            ${GIT_HASH}"
	@echo "NOW:                 ${NOW}"

clean::
	rm -rf ${clean_dirs} 

view-pages::
	@python -m webbrowser "${pages_url}" || \
		$(error "ERROR: I could not open the GitHub Pages URL. Try ⌘-click or ^-click on this URL instead: ${pages_url}")

view-local:: setup-jekyll run-jekyll

# Passing --baseurl '' allows us to use `localhost:4000` rather than require
# `localhost:4000/The-AI-Alliance/REPO_NAME` when running locally.
run-jekyll: clean
	@echo
	@echo "Once you see the http://127.0.0.1:${JEKYLL_PORT}/ URL printed, open it with command+click..."
	@echo
	cd ${docs_dir} && \
		bundle exec jekyll serve --port ${JEKYLL_PORT} --baseurl '' --incremental || \
		${MAKE} jekyll-error

setup-jekyll:: ruby-installed-check ruby-gem-installation bundle-command-check bundle-installation

.PHONY: ruby-installed-check ruby-gem-installation bundle-command-check bundle-installation
.PHONY: jekyll-error ruby-missing-error gem-missing-error gem-error bundle-error bundle-missing-error

ruby-gem-installation::
	@echo "Updating Ruby gems required for local viewing of the docs, including jekyll."
	gem install jekyll bundler jemoji || ${MAKE} gem-error

bundle-installation::
	bundle install || ${MAKE} bundle-error
	bundle update html-pipeline || ${MAKE} bundle-error

ruby-installed-check:
	@command -v ruby > /dev/null || ${MAKE} ruby-missing-error
	@command -v gem  > /dev/null || ${MAKE} gem-missing-error
	@ruby --version | grep -q 'ruby 3' || ${MAKE} ruby-version-error

bundle-command-check:
	@command -v bundle > /dev/null || \
		${MAKE} bundle-missing-error 

# NOTE: We call make to run these %-error targets, because if you try
# some_command || $(error "didn't work"), the $(error ...) function is always
# invoked, independent of the shell script logic. Hence, the only way to make
# this invocation conditional is to use a make target invocation, as shown above.
jekyll-error:
	$(error "ERROR: Failed to run Jekyll. Try running 'make setup-jekyll'.")
ruby-missing-error:
	$(error "ERROR: 'ruby' is required. ${ruby_installation_message}")
ruby-version-error: show-ruby-version
	$(error "ERROR: The wrong version of 'ruby' was found. ${ruby_installation_message}")
show-ruby-version:
	@echo "Ruby version found:"
	@ruby --version
gem-missing-error:
	$(error "ERROR: Ruby's 'gem' is required. ${ruby_installation_message}")
gem-error:
	$(error ${gem-error-message})
bundle-error:
	$(error ${bundle-error-message})
bundle-missing-error:
	$(error "ERROR: Ruby gem command 'bundle' is required. I tried 'gem install bundle', but it apparently didn't work!")