search

eclipse-ocl / org.eclipse.ocl

Eclipse Public License 2.0
0 stars 0 forks source link

[releng] OCL Help TOC doesn't appear. #639

Closed eclipse-ocl-bot closed 3 hours ago

eclipse-ocl-bot commented 3 hours ago

| --- | --- | | Bugzilla Link | 337202 | | Status | CLOSED FIXED | | Importance | P1 normal | | Reported | Feb 15, 2011 07:13 EDT | | Modified | May 27, 2011 03:13 EDT | | Version | 3.1.0 | | Reporter | Adolfo Sanchez-Barbudo Herrera |

Description

My error log shows the following related errors when openning help contents:

eclipse.buildId=I20110127-2034\ java.version=1.6.0_23-ea\ java.vendor=Sun Microsystems Inc.\ BootLoader constants: OS=win32, ARCH=x86_64, WS=win32, NL=es_ES\ Framework arguments: -product org.eclipse.epp.package.modeling.product\ Command-line arguments: -os win32 -ws win32 -arch x86_64 -product org.eclipse.epp.package.modeling.product

Error\ Tue Feb 15 12:07:27 GMT 2011\ Error reading help table of contents file /"org.eclipse.ocl.doc/topics_Reference.xml" (skipping file)

java.io.FileNotFoundException\ at org.eclipse.help.internal.toc.TocFileParser.parse(TocFileParser.java:49)\ at org.eclipse.help.internal.toc.TocFileProvider.getTocContributions(TocFileProvider.java:47) ...[trimmed]

eclipse.buildId=I20110127-2034\ java.version=1.6.0_23-ea\ java.vendor=Sun Microsystems Inc.\ BootLoader constants: OS=win32, ARCH=x86_64, WS=win32, NL=es_ES\ Framework arguments: -product org.eclipse.epp.package.modeling.product\ Command-line arguments: -os win32 -ws win32 -arch x86_64 -product org.eclipse.epp.package.modeling.product

Error\ Tue Feb 15 12:07:27 GMT 2011\ Error reading help table of contents file /"org.eclipse.ocl.doc/toc.xml" (skipping file)

java.io.FileNotFoundException\ at org.eclipse.help.internal.toc.TocFileParser.parse(TocFileParser.java:49)\ at org.eclipse.help.internal.toc.TocFileProvider.getTocContributions(TocFileProvider.java:47) ...[trimmed]

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Feb 15, 2011 07:32

As a first insight, I think that the problem is that the javadoc is not generated by the buckminster build...

Looking into this.

Regards,\ Adolfo.

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Feb 18, 2011 09:00

Well, Our build/publishing process has been configured to:

  1. Generate javadoc during the build process which will be included as part of the result artifacts of the build.
  2. Publish the javadoc from the last successful build, in the correspondent javadoc area. Currently:

http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/index.html

I also have a patch ready for commit to fix the OCL API Reference.

However, there is also another problem. There are some documentation concerning the extension points which are expected by the Help, which is not present in the doc plugin, and I suspect that it was generated by the same process which generated the javadoc.

I think that all these questions concerning this pde-generated documentation + buckminster should be moved up to the PMC.

By the way, I would like to solve this bug without expending more time about what to do with the extension-point documentation. Moreover, there are a lot of projects (whose builds are based on buckminster) which are not including any API Reference (javadoc and extension points) in their documentation plugins.... So I think we could:

  1. Solve this bug in the current state (without any extension point doc).
  2. Move the question/problem to the PMC
  3. Fix (if apply) any pendant documentation issue (depending on what PMC says).

Comments ?

Cheers,\ Adolfo.

eclipse-ocl-bot commented 3 hours ago

By Ed Willink on Feb 18, 2011 11:01

(In reply to comment #2)

Comments ?

Once you assign a bug to yourself, you stop traffic going to mdt-ocl inbox, that all committers should watch, so unless a committer added as CC on first notification you won't have anyone listening.

I only picked this up becuase of your email reference.

I suggest not assigning.

So I think we could:

  1. Solve this bug in the current state (without any extension point doc).
  2. Move the question/problem to the PMC
  3. Fix (if apply) any pendant documentation issue (depending on what PMC says).

I thought we'd agreed to have Javadoc as a reference to the www area, so that there is very little mandatory build activity.

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Feb 18, 2011 11:37

(In reply to comment #3)

(In reply to comment #2)

Comments ?

Once you assign a bug to yourself, you stop traffic going to mdt-ocl inbox, that all committers should watch, so unless a committer added as CC on first notification you won't have anyone listening.

I only picked this up becuase of your email reference.

I know, that reference in the email was intentional ;P\

I suggest not assigning.

I don't agree:

It's my task when requiring extra information to ensure that interested people are in CC. In this case instead of adding you to cc I simply sent an email to dev list to send extra information.

So I think we could:

  1. Solve this bug in the current state (without any extension point doc).
  2. Move the question/problem to the PMC
  3. Fix (if apply) any pendant documentation issue (depending on what PMC says).

I thought we'd agreed to have Javadoc as a reference to the www area, so that there is very little mandatory build activity.

When I said "current state" I meant including the progress I've made (including the javadoc). So what I'm really suggesting is solving the bug by:

Cheers,\ Adolfo.

eclipse-ocl-bot commented 3 hours ago

By Ed Willink on Feb 18, 2011 12:27

(In reply to comment #4)

  • Removing the content from the TOC which concerns extension-point documentation, specifically "org.eclipse.ocl.environments" which will be deprecated in Indigo anyway, am I wrong ?

We shouldn't remove functionality just because we don't understand it.

Part of the early post-Indigo API 'alignment' will be attempting to ensure that we have a new functionality for all old functionality. Till I understand the EP, I cannot comment on its replacement.

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Feb 18, 2011 12:56

Ed

I'm not saying to remove the extension-point...

I only want to remove from our o.e.ocl.doc plugin, the Help's topic which contains the description/documentation about said extension point (which was inserted in our doc plugin by the old build system)...

The extension point and its description/documentation will obviously be in the org.eclipse.ocl plugin

Cheers,\ Adolfo.

eclipse-ocl-bot commented 3 hours ago

By Axel Uhl on Feb 19, 2011 12:10

(In reply to comment #2)

  1. Solve this bug in the current state (without any extension point doc).
  2. Move the question/problem to the PMC
  3. Fix (if apply) any pendant documentation issue (depending on what PMC says).

How about consulting the PMC for advice regarding the extension point docs? Also, do we know of other projects where these docs are generated properly? Any possibility we may get their advice, too?

Best,\ -- Axel

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Feb 24, 2011 13:02

Sure,

I've just sent an email to modeling-pmc newsgroup:

http://dev.eclipse.org/mhonarc/lists/modeling-pmc/msg01964.html

Regards,\ Adolfo.

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Mar 11, 2011 07:48

Changes committed to HEAD.

Although this works in my second instance, I'll verify the fix (and resolve the bug) using the Modeling Indigo M6 installation.

Cheers,\ Adolfo.

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Mar 30, 2011 05:35

Now that M6 modeling distribution is available, I could verify that OCL Help doesn't work...

I guess that I'll definitely need to deal with that build.xml, providing that now we don't want to include javadoc in the doc plugin.

Looking into this...

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Apr 12, 2011 08:28

The problem was that the previous system build was not relying on the build.properties file to produce the doc bundle/jar. Buckminster relies on this file to generate the jar, and some files (including TOC files) needed to be specified in the build.properties file so that they were included into said jar.

Besides, now that I know how to interfere a component build done by buckminster, I've also successfully tried to invoke an ant task which creates the extension point documentation into the doc plugin. The javadoc creation counterpart has been commented because as discussed weeks ago, we don't want to include javadoc into the documentation plugin.

To test the documentation you could update the OCL Extender feature (which includes the documentation) using our P2 nightly repository [1].

[1] http://wiki.eclipse.org/MDT/OCL/Dev/Releng/P2_Repositories_Organization#Nightly_Repository

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Apr 13, 2011 04:29

Axel detected that help's links which refer to the javadoc are not working.

The problem is the link URLS are relative to a references/javadoc folder which is not currently built inside the plugin. We must use absolute URLs pointing to our javadoc area (http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/)

eclipse-ocl-bot commented 3 hours ago

By Adolfo Sanchez-Barbudo Herrera on Apr 13, 2011 06:11

I've checked some links in the Help and they are now working using the last published build.

I must note that there are two external javadoc references, which may be considered to be updated in future releases

http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/\ http://download.eclipse.org/modeling/emf/emf/javadoc/2.6.0/

Resolving as fixed.

eclipse-ocl-bot commented 3 hours ago

By Ed Willink on May 27, 2011 03:13

Closing