The Doc Days of Summer

It’s been overcast and raining here in Victoria B.C. (Canada) over the past 2 weeks. It’s a long way from the dog days of summer, but a good time to focus on docs.  In fact, the Eclipse team has been focusing on documentation during this final release candidate.  In particular, the p2 team is putting some docs together on our new API (Yes, p2 has “real” API now).

Last year Andrew Niefer gave me a few tips on self-hosting the doc / help contents and I thought I would share these.

The help contents are written in HTML files and live in OSGi bundles (like everything else).  For example, the platform doc lives in org.eclipse.platform.doc.isv. Once you have your bundle loaded (from CVS, git, wherever) you can edit the contents like any HTML other document.  When you want to see how the contents will appear to the user, simple launch the org.eclipse.help.base.infocenterApplication, and specify a port as a VM argument (-Dserver_port=4419 for example).

Once running, you can now browse the help contents using your favorite browser (and even change the contents on the fly).

Of course if we get our butts in gear and follow David Green’s advice, we won’t need to edit our docs this way.