Home » Archived » Mylyn Intent » Plans for Eclipse Phoenix website integration?
| Plans for Eclipse Phoenix website integration? [message #754932] |
Sat, 05 November 2011 10:14  |
|
Hi,
we are currently seeking a documentation system that nicely fits our requirements, which are:
* integration into eclipse.org website look and feel
* Eclipse Help Integration
* Referencing resources in the workspace from documentation
* few things more 
Xdoc seems to be a good fit for these needs. How about Mylyn Intent?
We currently document things in wiki.eclipse.org and generate the Eclipse Help from these pages using Mylyn Wikitext. I guess with yuor WikiText exporter this should work reasonably well. How about the other two features (integrating with the eclipse.org phoenix system) and referencing java types and method from documentation?
BTW:
At the moment it feels like betting on horses which technology to use (Xdoc or Mylyn Intent). Are there any plans to merge these both projects or to define/use an interchangeable format that allows one to flip from one technology to the other?
Thanks,
Marcel
|
|
|
| Re: Plans for Eclipse Phoenix website integration? [message #755355 is a reply to message #754932] |
Tue, 08 November 2011 08:54  |
|
Hi Marcel, thanks again for your interest in Intent !
First of all, I'll put during the week a transcript of my Intent talk at
EclipseCon Europe. This transcript will explain in details how does
Intent work and what's planned.
> * integration into eclipse.org website look and feel
Actually my next task on Intent is to write an export mechanism. You may
notice that Intent already provides cool generators to export Wikitext
in Latex & HTML. Fabian created UI for these generators, get the latest
Intent build
https://hudson.eclipse.org/hudson/job/mylyn-docs-intent-0.7-nightly/ to
see what they look like.
Good idea to create a full website from the doc, I'll add it to my roadmap.
> * Eclipse Help Integration
Same answer here, that's planned.
> * Referencing resources in the workspace from documentation
Yeah, that's the whole point of Intent. I invite you to check the Intent
tutorial http://wiki.eclipse.org/Intent/Getting_Started to see how you
can reference concrete artifacts inside an Intent document.
I've not written doc about synchronization with java code yet, but again
I'll do it soon. Actually Intent allows you to synchronize any kind of
technical artifact, as long as you have a synchronization bridge for
this kind of artificat. Default synchronization bridges to synchronize
Java, Manifest.MF files... will be provided by Intent.
To write your own synchronization bridge, you only have to :
- Be able to represent a specific kind of technical artifact (for
example Java Classes) as a model (That's what the
"org.eclipse.mylyn.docs.intent.retro" plugin is about)
- Be able to detect when a change occur on this kind of technical
artifact. This feature is optional, and allows Intent to detect
synchronization issues in real-time
> Xdoc seems to be a good fit for these needs. How about Mylyn Intent?
Actually, when we started Intent we proposed to work with the Xdoc project.
The scopes of Intent & Xdoc are a bit different :
- Xdoc is a documentation langage that allows you to make direct
references to javafiles. If you delete or rename your file, you will be
able to detect it with Xdoc.
- Intent is a documentation langage that allows you to synchronize your
documentation with any kind of technical artifcat (java classes,
MANIFEST.MF, models, a code example on the internet...). If any
modification that you consider as relevant (adding a method, changing a
dependency, write javadoc...) occurs, then the synchronization bridge
will warn Intent and we will put synchronization issue markers inside
your doc to indicate which part of the doc have to be updated due to
your change.
Additionally, Intent provides an extensible Validation Framework that
allows you to constraint your software development (you can define rules
like "Any Action displayed to the end-user should be covered by at least
one SWTBOT Test" for example).
So I think Xdoc could be seen as a subset of Intent, dedicated to
synchronize your doc with java code. Any Xdoc commiter is free to argue
with me on this point :)
> BTW:
> At the moment it feels like betting on horses which technology to use
> (Xdoc or Mylyn Intent). Are there any plans to merge these both projects
> or to define/use an interchangeable format that allows one to flip from
> one technology to the other?
Well Intent syntax actually uses 2 langages :
- a syntax for pure documentation zone (for now on it's any Wikitext
based syntax)
- a syntax to describe model fragments
For the both syntax, we are planning to work on extensiblity so that you
can contribute your own. In that context, Xdoc could be used to write
the pure documentation zones. So the bridge between Xdoc & Intent will
be made this way, although we may loose the Xdoc capability to reference
directly java class, I'll have to think about that.
Anyway, thanks a lot for this questions, do not hesitate to ask me more !
Cheers,
Alex
|
|
|
| Re: Plans for Eclipse Phoenix website integration? [message #755371 is a reply to message #755355] |
Tue, 08 November 2011 09:54 |
|
Thanks Alex for your detailed answer!
>> * integration into eclipse.org website look and feel
> I'll add it to my roadmap.
Excellent
>> * Referencing resources in the workspace from documentation
> I've not written doc about synchronization with java code yet, but again
> I'll do it soon. ... Default synchronization bridges to synchronize
> Java, Manifest.MF files... will be provided by Intent.
Is there an estimate when this will be ready? I'm unfortunately not a EMF modeling user, thus, depend on Java mostly. In particular, I would like to integrate code snippets and reference Java files in the documentation.
I don't wanna push you towards implementing a certain feature. I just would like to know if this is planned for next week, next month or in next 3 months We have used wiki pages and word so far, and it probably doesn't make a big difference waiting little more. Thanks.
A slightly different use case/question:
One of the things I like about xdoc is that it allows to create your own tags (or shortcuts). For instance, we have to document several REST APIs and - somewhat in the spirit with docbook - we can define our own tags with separate renderings. Will Mylyn Intent support this too (in some way)?
Best,
Marcel
|
|
|
| Re: Plans for Eclipse Phoenix website integration? [message #756038 is a reply to message #755371] |
Thu, 10 November 2011 15:02 |
|
Hi Marcel,
>>> * integration into eclipse.org website look and feel
>> I'll add it to my roadmap.
>
> Excellent :)
Actually if you test a recent Intent nightly build you will see that we
already started to work on HTML & Latex exports for textile files.
Righ-click on any Textile file and select Intent > Export as HTML or
Export as Latex. I'm still hesitating between several librairies to make
the best HTML export for Intent documents.
>>> * Referencing resources in the workspace from documentation
>
> Is there an estimate when this will be ready? I'm unfortunately not a
> EMF modeling user, thus, depend on Java mostly. In particular, I would
> like to integrate code snippets and reference Java files in the
> documentation.
>
> I don't wanna push you towards implementing a certain feature. I just
> would like to know if this is planned for next week, next month or in
> next 3 months :) We have used wiki pages and word so far, and it
> probably doesn't make a big difference waiting little more. Thanks.
>
As I explained in this post
http://www.eclipse.org/forums/index.php/t/261790/ , the Java
syncrhonization already works, the only thing missing is a Metamodel
that would fit the community needs.
I don't have much time to adress this issue, I would really like to
improve Intent existing features and implement the "must-have" features.
But it's very easy to look at the "retro" example and provide your own
synchronization bridge.
>
> A slightly different use case/question:
> One of the things I like about xdoc is that it allows to create your own
> tags (or shortcuts). For instance, we have to document several REST APIs
> and - somewhat in the spirit with docbook - we can define our own tags
> with separate renderings. Will Mylyn Intent support this too (in some way)?
I'm not sure to understand what you mean by "tags", I'll study what Xdoc
does and keep you in tuch.
Cheers,
Alex
|
|
|
Goto Forum:
Current Time: Tue Apr 16 18:46:22 GMT 2024
Powered by FUDForum. Page generated in 0.26765 seconds |
] 
Search
Help
Register
Login
Home
