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 3rd and 18th 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:
Document | Description |
---|---|
Javadoc | Javadoc API documentation. |
Test Javadoc | Test Javadoc API documentation. |
Source Xref | HTML based, cross-reference version of Java source code. |
Test Source Xref | HTML based, cross-reference version of Java test source code. |
Dependency Updates Report | Provides details of the dependencies which have updated versions available. |
Plugin Updates Report | Provides details of the plugins used by this project which have newer versions available. |
Property Updates Report | Provides details of properties which control versions of dependencies and/or plugins, and indicates any newer versions which are available. |
Tag List | Report on various tags found in the code. |
dependency-check:aggregate | Generates an aggregate report of all child Maven projects providing details on any published vulnerabilities within project dependencies. This report is a best effort and may contain false positives and false negatives. |
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
Panel | ||
---|---|---|
| ||
[remote "origin"] |
3) Add a new crontab line for the build job, 1 minute in the future
Panel |
---|
[@i2midev6 ~]$ sudo -u grprdist crontab -e 09 13 * * * /var/grouper-docs/bin/buildGrouperDocs.sh > /var/grouper-docs/log/grouper-docs.log 2>&1 |
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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:
- Someone checking out the project can see docs without building (sometimes figuring out config files can be time consuming)
- Javadoc would be versioned, and we would be able to browse any branch, any time
- 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)
- 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:
No Format |
---|
"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
No Format |
---|
#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)
No Format |
---|
<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)
...