Refresh documentation build

[eclipse-modisco-bot]

| --- | --- | | Bugzilla Link | 553132 | | Status | NEW | | Importance | P3 normal | | Reported | Nov 17, 2019 06:31 EDT | | Modified | Nov 27, 2019 02:27 EDT | | Blocks | 552988 | | See also | 448088 | | Reporter | Ed Willink |

Description

The current Modisco build relies on scripts in EMF Facet Releng. The Mylyn MediaWiki scripts look rather like the Mylyn Textile scripts used by OCL which got harder and harder to maintain on Hudson/Jenkins ultimately leading to a deecision to treat documentation as 'source'; manually auto-generated and then committed to GIT. Except Javadoc that is optionally run as part of the build and promoted to downloads rather than bloating the distribution.

The same policy seems appropriate for Modisco. Try to get the build scripts to work locally, else just copy everything fron the most recent distrubution.

Change Javadoxc references to a downloads location.

[eclipse-modisco-bot]

By Ed Willink on Nov 19, 2019 09:55

(In reply to Ed Willink from comment #0)

The same policy seems appropriate for Modisco. Try to get the build scripts to work locally, else just copy everything fron the most recent distrubution.

Each Modisco doc plugin has a build.xml that, once Mylyn WikiText installed, just works (deceptively fast and with minimal console comfort messages) when run as Run As Ant Build .

Possibly Mylyn has now stabilized. Possibly because the Modisco build generates only Eclipse Help whereas the OCL build does HTML help and PDF too.

If it's that simple it's worth trying to activate the Maven ant run.

[eclipse-modisco-bot]

By Ed Willink on Nov 19, 2019 10:02

(In reply to Ed Willink from comment #1)

If it's that simple

It's never that simple. wikitext seems to need javax.lang.model which is a boring bit of the JDK in Java 8, but Tycho seems to refuse to find it despite using similar approaches to javax.annotation,

Bug 543511 suggests that Oracle are messing around again for modules, but unlike javax.annotation which has an Orbit solution javax.lang.model doesn't.

Too hard. Try to do manual generation.

[eclipse-modisco-bot]

By Ed Willink on Nov 20, 2019 05:30

(In reply to Ed Willink from comment #1)

If it's that simple

It's never that simple. wikitext seems to need javax.lang.model which is a boring bit of the JDK in Java 8, but Tycho seems to refuse to find it despite using similar approaches to javax.annotation,

Bug 543511 suggests that Oracle are messing around again for modules, but unlike javax.annotation which has an Orbit solution javax.lang.model doesn't.

Too hard. Try to do manual generation.

Most done piecemeal, but Fabien on modisvo-dev identified GASTM etc missing.

Doh! There is a single /org.eclipse.modisco.doc/doc-build-all.xml that generates them all.

/org.eclipse.modisco.doc/Generate Modisco Help Documentation.launch added to make it more obvious.

[eclipse-modisco-bot]

By Ed Willink on Nov 25, 2019 09:04

Non-Javadoc documentation pushed to master for 2019-12M3.

Javadoc still to do.

Revision of high level/introductory documentation still to do.

[eclipse-modisco-bot]

By Ed Willink on Nov 27, 2019 02:27

(In reply to Ed Willink from comment #4)

Revision of high level/introductory documentation still to do.

Some Wiki tweaks done.

Javadoc still to do.

There is /org.eclipse.modisco.doc/javadoc-build.xml that invokes a custom Javadoc task. It clearly hasn't been run for a long time since it expects the same "plugins" folder that would have made pom-less Tycho much easier. It seems at some point a sensible plugin layout was changed to the currently unhelpful flat structure.

Fixing the path and the execution fails with

Cannot run program "C:\Program Files\Java\jdk1.8.0_231\bin\javadoc.exe": CreateProcess error=206, The filename or extension is too long

Migrating the ANT build from OCL and we get the same error.

It appears that the enumeration of all the plugin locations exceeds some limit.

Attempting to use wildcards doesn't help; presumably the outer ANT processing computes a flat command line for javadoc.exe.

Choices:

• find a way for Ant to pass wildcards to javadoc.exe
• invoke javadoc.exe more directly with a command script
• partition the Javadoc generation into multiple sessions

Whatever, quite a bit of pain for something nobody will ever use.