From: chap at anastigmatix.net (Chapman Flack)
Date: Sat, 05 Sep 2015 15:35:09 -0400
Subject: [Pljava-dev] documentation site makeover
Message-ID: <55EB43ED.601@anastigmatix.net>

You may love it, you may hate it, you may go "hmm, ok."

http://tada.github.io/pljava/

I had been playing earlier with the site-autogeneration features
in maven, mostly just to get the javadocs, and when I contacted
Thomas to ask about repurposing the github.io pljava site to host
that, he set my push bit, so I guess that meant "ok, try it out"
and there it is. I did a bunch of test runs using site:stage on my
local machine, but the time comes to test the maven plugin that
publishes to the real site, and ... well, it worked. :)

Aesthetically, it's ... ok, it's exactly what you get out of
maven without customizing much. What can I say, I'm a geek, can
I go write code now? :) There are a bunch of customizing/styling/
skinning features available to play with, I just haven't. But pull
requests are easy....

It should be easy enough to revert, if this seems horrible.

My original idea was: keep the existing wiki as the main documentation
and go-to URL for the project, and use the github.io site only for this
autogenerated tech doc stuff. Maven, of course, has other ideas, because
Maven's philosophy is "Convention Over Configuration" and Maven's
convention is to assume that whatever site Maven is building is The Site,
and relative references are assumed to be within it, and heaven help you
with the configuration if that isn't what you're trying to do.

So I ended up telling Maven it was building The Site, and then writing
a short main page to go there (which mostly has links back to the wiki).

In the grand scheme, maybe that isn't so bad.  Most of the existing
documentation is written in markdown at present, and that isn't one
of the default languages for the maven site builder, but there's a
plugin for it, and I added that. The main page I created is written
in markdown, so that works, and proves it would not be hard to move
over the existing docs in markdown that currently make up the wiki.

Thomas seems to be chary about having a widely editable wiki, so the
content there hasn't been very actively updated, and GitHub's usual
convenient pull-request machinery doesn't work for the wiki either.
Moving the content to src/site in the normal pljava repo would mean
it could be updated with normal pull requests (and doc updates could
even be in the same pull as code changes they relate to), and that
might end up being a better fit for PL/Java's development process.

Anyway, here's my after-the-fact announcement of the new stuff at
http://tada.github.io/pljava/.  Now I should go back and commit
the source changes that made it....

Cheers,
-Chap