Page History

Grouper Javadoc, cross-referenced source code, and other project and module reports are at http://software.internet2.edu/grouper/doc/ . The website has subdirectories for the currently active and recent versions, and the alias main links to the currently active Git branch. The active Git branch is updated on the 3^rd and 18^th of every month by a cron job on i2midev6 (service user grprdist) , and pulled via rsync to webprod3. The same site can also be built locally using Maven command mvn -f grouper-parent --clean site site-deploy. The site directive will build the site locally in a subdirectory of grouper-parent, and site-deploy will stage it in directory /tmp/groupersite.

Reports available for each release module include:

Building the public-facing site

1) On i2midev6, edit /var/grouper-docs/bin/buildGrouperDocs.sh

Change the branch it's checking out. Ideally this should be the same as what is in Git, file grouper/misc/buildGrouperDocs.sh. Once it's working on i2midev6, you can check the changes into Git.

2) Force create the new branch so pulls work

The installed git version on i2midev6 is very old; normal branch creation doesn't work well

cd /var/grouper-docs/git/grouper
sudo -u grprdist vi .git/config 
sudo -u grprdist git checkout GROUPER_4_BRANCH

3) Add a new crontab line for the build job, 1 minute in the future

May take about 45 minutes to complete. Check the output in /tmp/groupersite, plus the log file in /var/grouper-docs/log/grouper-docs.log

Delete the crontab entry once it completes successfully. Going forward, it should only update on the 3rd and 18th.

4) Update target folders on webprod3

cd /home/htdocs/software.internet2.edu/grouper/doc/
mkdir 4.x
rm main master
ln -s 4.x main
ln -s 4.x master
nano index.html    # edit links for branches and download packages

5) Force copy the new site into the folder (rather than waiting for the rsync scheduled job to pick it up)

There is some kind of rsync job running on webprod3 as user grprdist that will pick up the site from i2midev6. The admins didn't want i2midev6 to be pushing the files since webprod3 is a production machine, so instead there is a pull from webprod3

rsync -rtzv i2midev6:/tmp/groupersite /home/cer/grouper-doc/4.x
mv 4.x/* 4.x

6) Verify public page https://software.internet2.edu/grouper/doc/

7) Fix file permissions

We don't have root on webprod3, so the cron job may fail since we can't set the user/group permissions in a way that grprdist can update the files. Get an admin to do this

chown -R grprdist:grprdist /home/htdocs/software.internet2.edu/grouper/doc/4.x

Legacy Javadoc

Between 2014 and 2019, the git branch gh-pages was updated with the javadoc on every commit, which effectively published it on http://internet2.github.io/grouper/ . That method has been decommissioned due to the size explosion in the git repository. The main page of the github.io site now redirects to the software.internet2.edu site.

Here is an example of Javadoc in CVS with ViewVC

There are some advantages to Javadoc being stored in CVS and accessible over viewVC:

1. Someone checking out the project can see docs without building (sometimes figuring out config files can be time consuming)
2. Javadoc would be versioned, and we would be able to browse any branch, any time
3. The history of the documentation with comments would be able to be viewed (as long as we commit the new javadoc when committing the code)
4. It would be instantly available (note there is a delay of committing to being viewable on ViewVC of an hour or more), no need to move to a static server

There is a disadvantage that if ViewVC goes away we will have stale links...  this is from SteveO:

"we intend to support viewvc or something like it going forward.

we don't guarantee that we will keep urls the same if we update to a new piece of software but i do not foresee that anytime soon."

To get Javadoc to work on ViewVC, some massaging needs to happen:

    1. The branch will be in the URL, so the branch needs to be known by the build script, so get this from a new property in build.properties

#cvs branch
cvs.branch=HEAD

    Note: If the code is branched, this property will need to be changed in the new branch...   it might be possible to get from a CVS metadata file...

    2. The javadoc generation should not commit new files each time it is generated unless something changes.  So the timestamp should be removed. (-notimestamp)

<javadoc destdir="doc/api" classpathref="ws.class.path"       access="public"
			additionalparam="-notimestamp" >
			<packageset dir="src/grouper-ws" defaultexcludes="yes">
				<include name="edu/internet2/middleware/grouper/**" />

			</packageset>

			<link href="http://struts.apache.org/1.2.x/api/"       />
			<link href="http://java.sun.com/j2ee/sdk_1.3/techdocs/api"       />
			<link href="http://java.sun.com/j2se/1.4.2/docs/api"       />

		</javadoc>

    3. After the javadoc is generated, the links need to be changed so that it is compatible with the URL params in viewvc... (see example in grouper-ws)

...