Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 420663

Summary:	Move API & user docs out of the Orion wiki
Product:	[ECD] Orion	Reporter:	Mark Macdonald <mamacdon>
Component:	Doc	Assignee:	Project Inbox <orion.doc-inbox>
Status:	RESOLVED WONTFIX	QA Contact:
Severity:	normal
Priority:	P3	CC:	curtis.windatt.public, john.arthorne, ken_walker, Michael_Rennie
Version:	3.0
Target Milestone:	---
Hardware:	PC
OS:	Windows 7
Whiteboard:

Description Mark Macdonald

2013-10-29 15:23:18 EDT

Orion uses the Eclipse online help system to embed documentation into its builds.

Orion's docs (Developer Guide and User's Guide) are generated from a subset of the Orion wiki [1] by an Ant script using Mylyn WikiText, which fetches the MediaWiki source code behind Orion's wiki pages, and converts it into HTML.

I have found this problematic. The doc generation tends to get broken by all kind of innocuous MediaWiki constructs, for example: 
 * HTML tags the WikiText parser does not understand
 * MediaWiki extensions or templates that the parser does not understand
 * Mismatched HTML tags

I would suggest moving our API docs into Markdown files kept in the client repository. At build time, we could auto generate Docbook+HTML for the Eclipse online help system to consume. (We might be missing a step here to convert Markdown into Docbook TOC's, not sure).

Opening this bug for discussion.

[1] https://wiki.eclipse.org/Orion
[2] http://wiki.eclipse.org/Mylyn/WikiText

Comment 1 Mark Macdonald

2013-10-30 13:44:28 EDT

It looks like the Mylyn WikiText plugin supports Markdown as an input language: bug 329528. So it may be feasible to use it to parse the .md docs from our repo and generate Eclipse help stuff (Docbook+HTML, or whatever it needs).

Comment 2 John Arthorne

2013-11-01 06:51:55 EDT

I like this idea. We could maybe use the API doc markdown syntax used by Node.js to make it potentially usable by tools as well:

http://nodejs.org/api/documentation.html#documentation_about_this_documentation

Comment 3 Michael Rennie

2013-11-01 09:52:59 EDT

(In reply to John Arthorne from comment #2)
> I like this idea. We could maybe use the API doc markdown syntax used by
> Node.js to make it potentially usable by tools as well:
> 
> http://nodejs.org/api/documentation.
> html#documentation_about_this_documentation

I really like this idea as well, especially the levels of API, it makes it very clear to people when asking for enhancements what is possible and we have no plans to change.

Comment 4 Ken Walker

2013-11-05 11:30:47 EST

I'm not sure I want to rely on Eclipse help any longer - I would rather produce doc that was entirely consumable by a client side JavaScript help system.  That way it could be used by our Node.js server as well.

Comment 5 Mark Macdonald

2013-11-05 12:18:09 EST

I just wanted to add that the sections of the Developer Guide dealing with extension point APIs (for example [1] [2]) need to be moved into formal docs. We should reuse whatever solution we settle on for documenting our JS modules (whether Node.js, jsdoc3, etc)

Currently our extension APIs are only documented in wiki text, which is not strict enough to be used for content assist, API conformance validation and so on.

Tutorials, howtos, and other human-facing documentation can remain in non-rigorous markup formats.

[1] http://wiki.eclipse.org/Orion/Documentation/Developer_Guide/Plugging_into_the_editor#orion.edit.contentAssist
[2] http://wiki.eclipse.org/Orion/Documentation/Developer_Guide/Plugging_into_the_editor#orion.edit.editor

Comment 6 John Arthorne

2015-05-05 14:43:01 EDT

Closing as part of a mass clean up of inactive bugs. Please reopen if this problem still occurs or is relevant to you. For more details see:

https://dev.eclipse.org/mhonarc/lists/orion-dev/msg03444.html