Adds yard and makefile with development commands

[JPrevost]

• 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

[jazairi]

Confirmed that all make commands work as expected. I suggested an update to the reference docs, as it seems that make docserver will not work unless you first install the gem.

Poked around the generated docs a bit, as well, but will do more once #49 lands. I think this will make a big improvement to our documentation practices; thanks for suggesting and implementing it!

[jazairi]

I'd suggest we document the prerequisite of gem install yard here. Without that, the make command fails (for me, anyway).

[JPrevost]

bundle install should cover that as it's in the bundle right?

[JPrevost]

We could have make install be run prior to every run of make docserver but I thin that would get annoying.

I'll update the readme to know that prior to running for the first time, bundle install or make install needs to be run.

My initial reaction was "but that's always the case for gems", but after having sat with this for a bit I think it's worth noting explicitly for this as it likely isn't clear it's a bundled gem that is doing this work. Thanks for pointing it out.

[jazairi]

I could've sworn that I got that error after running bundle install, which is why I mentioned it. I just tried this, though:

1. Run gem uninstall yard.
2. Try make docserver: returns rbenv: yard: command not found, as expected.
3. Run bundle install.
4. Try make docserver: the yard server starts up successfully.

I was so baffled by this that I looked at my shell history from where I first checked out the branch:

10123  git pull
10124  git checkout yard-and-makefile
10125  bundle install
10126  make docserver (this failed with 'command not found')
10127  rm -rf .yardoc (tried clearing the cache as suggested, in case there was any)
10128  make docserver (failed again)
10129  gem install yard
10130  yard server --reload (working now)

After that, make docserver worked as well, as expected. So, I think it's still possible for yard not to work even if you do run bundle install first, but I'm not exactly sure why. Since I can't replicate it, I think I'm fine with the additional tip text as-is.

[JPrevost]

Super weird. Thanks for confirming so we can keep an eye out for this in the future.

[jazairi]

See my non-blocking comment. Something very weird was happening in my shell, but I can't replicate it. I think we should have Matt try the build process when he returns to see if that was a one-off oddity or something that should be documented.

[jazairi]

I could've sworn that I got that error after running bundle install, which is why I mentioned it. I just tried this, though:

1. Run gem uninstall yard.
2. Try make docserver: returns rbenv: yard: command not found, as expected.
3. Run bundle install.
4. Try make docserver: the yard server starts up successfully.

I was so baffled by this that I looked at my shell history from where I first checked out the branch:

10123  git pull
10124  git checkout yard-and-makefile
10125  bundle install
10126  make docserver (this failed with 'command not found')
10127  rm -rf .yardoc (tried clearing the cache as suggested, in case there was any)
10128  make docserver (failed again)
10129  gem install yard
10130  yard server --reload (working now)

After that, make docserver worked as well, as expected. So, I think it's still possible for yard not to work even if you do run bundle install first, but I'm not exactly sure why. Since I can't replicate it, I think I'm fine with the additional tip text as-is.