Enable maven features to build a basic tech-detail site #44
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
With these pom additions, `mvn clean compile site site:stage` will build a directory `target/staging` that contains a web site with a bunch of autogenerated technical reference and javadocs for the project. This should not _substitute_ for the user-oriented documentation on the wiki, but should be linked to _from_ the wiki for easy access to deeper detail. In the default output the javadocs are a bit buried (click a project module, then click Project Reports), but that should be ok as they can be linked to easily from the user docs on the wiki and that is probably how most people would get there. I'm sure there are lots of possible configuration tweaks in what maven can generate, but for now I think it would be a big improvement just to have tech refs on the site at all. I think the `gh-pages` site would be an ideal place for this generated stuff to be pushed. There is stuff in the `gh-pages` branch right now but it seems to be the same stuff that's on the wiki, and the wiki is probably the right place for it. So a clean empty `gh-pages` orphan branch could be made, and `tada.github.io/pljava` could be where the autogenerated reference material goes. I believe github offers a dedicated maven plugin that can automagically push the generated site there.
That creates some redundancy, such as documenting both a field and the enum that's only used there, but those javadoc gaps are so unsightly!
|
Not sure what you mean by enabling http://tada.github.io/pljava/. It's been enabled ever since the gh-pages were created. Did you try it? |
thallgren
added a commit
that referenced
this pull request
Jul 21, 2015
Enable maven features to build a basic tech-detail site
|
This is excellent. Thanks! |
|
Hmm, so it is ... very strange, I must have mistyped the URL or something -Chap On 07/21/15 02:50, Thomas Hallgren wrote:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Now
mvn clean package site site:stagewill produce a (very basic, uncustomized) directory tree representing a web site undertarget/staging. It includes generated javadocs for everything (and I've also spent a bit of time completing javadocs, at least the ones I noticed missing and felt competent to write).In order to make maven do this, I had to put a site URL into
pom.xmland you will see that I usedhttp://tada.github.io/pljava/which is (I think) what the project's GitHub Pages URL would be, if you were to enable that feature. So, you may detect in this pull request a faint, implicit suggestion about doing that. :)I can see in the repository that there already is a
gh-pagesbranch where you did some experimenting in early 2013, but that seems to have been just the same content that is now the wiki. What I would suggest is to keep the wiki, and enable thegh-pagessite for nothing but maven autogenerated technical docs. User Guide content on the wiki could then link to them when appropriate.Although I haven't tried it, I believe there is a GitHub-supplied plugin for maven that completes the process, so that a
mvncommand similar to mine above would build all the docs and put them on the GitHub Pages site.While I'm not sure how you feel about enabling the GitHub Pages site for that purpose, in any case merging this branch will allow anyone who downloads pljava to run the
mvncommand above and get a local set of the same docs.