Add theia plugin API documentation

[lucas-koehler]

What it does

• Add documentation on how theia's plugin API works and how to extend it.
• Add link to new documentation to README

Contributed on behalf of STMicroelectronics.

Signed-off-by: Lucas Koehler [email protected]

Note: This documentation is partly based on existing documentations https://github.com/eclipse/che/wiki/Writing-Theia-plugin-API and https://github.com/eclipse-theia/theia/wiki/Theia-Plugin-Implementation.

Review checklist

• As an author, I have thoroughly tested my changes and carefully followed the review guidelines

Reminder for reviewers

• As a reviewer, I agree to behave in accordance with the review guidelines

[vince-fugnitto]

Note: This documentation is partly based on existing documentations https://github.com/eclipse/che/wiki/Writing-Theia-plugin-API and https://github.com/eclipse-theia/theia/wiki/Theia-Plugin-Implementation.

@lucas-koehler should we consolidate the documentation from the now three different documents into a single one instead (even as different sections in the document). Having three sources of information would mean that the information is harder to discover, and might become outdated more quickly. Any thoughts? It can either be a single wiki page or a document in the repo although having the wiki reduces the turnaround for the documentation updates from being merged.

[JonasHelming]

@vince-fugnitto The wiki makes it hard to receive contributions. Therefore, I would be in favor of removing our wiki page (in the Theia project) after this is merged (link the page to this document). About the Che document, the Che team has to decide on how to proceed. (@tsmaeder )

[lucas-koehler]

@vince-fugnitto Thanks for the feedback. From my POV the doc in this PR contains all relevant information present in the two linked wiki pages and could replace them. So I propose to go with @JonasHelming suggestion to remove the Theia wiki page (or link from it to the doc in case people have it saved as a reference somewhere) and let the che team decide on what to do with their wiki page :)

[thegecko]

I wrote something similar internally last week.

Some additional areas we may want to cover:

• Outline when to use Theia Plugin vs VS Code Extsnsion vs Theia Extension. In most cases, users may be looking for the rich UX of Theia extensions. This could be covered in external docs, but may be nice to include (at a high level)

• A concrete example of creating a new plugin namespace. This is hard to fathom from the bits of code copied into the linked document.

• Outline how a VS Code extension can 'upgrade` functionality using a custom namespace when run in Theia. This could just be a link to a sample project I'm working on ;)

[thegecko]

Is it VSCode or VS Code? ;)

[thegecko]

Could this benefit from a diagram?

[JonasHelming]

@thegecko : Great suggestion with the link, I believe we have the right target document here explaining the different extension mechanism: https://theia-ide.org/docs/extensions/

[lucas-koehler]

@thegecko Thanks for your review and ideas.

I unified the VS Code spelling and added a link to the extension mechanism overview to the Additional links section. It was also already linked in the beginning of the doc ;)
I added a diagram that hopefully makes the communication between theia and plugins a bit easier to understand.

Outline when to use Theia Plugin vs VS Code Extsnsion vs Theia Extension. In most cases, users may be looking for the rich UX of Theia extensions. This could be covered in external docs, but may be nice to include (at a high level)

I think this is now covered with linking the external doc

A concrete example of creating a new plugin namespace. This is hard to fathom from the bits of code copied into the linked document.

There is a link to a readme explaining how to add a new namespace in a separate extension. If this is not sufficient, I suggest tackling this separately

Outline how a VS Code extension can 'upgrade` functionality using a custom namespace when run in Theia. This could just be a link to a sample project I'm working on ;)

A link to an example sounds very helpful. I suggest you just add it to this doc once you are finished with that :)

[tsmaeder]

Maybe there's some stuff to be stolen from https://www.youtube.com/watch?v=KN2JUsFuEhU as well. Did I ever make the slide public on that one?

[thegecko]

Thanks for the updates, especially the diagram!

There is a link to a readme explaining how to add a new namespace in a separate extension.

Yeah, I think this readme is quite poor. It misses bits out.

[thegecko]

Here's the example repo I mentioned outlining a custom API namespace implementation and upgrading functionality in a VS Code extension for Theia. Shall we add it to this doc?

https://github.com/thegecko/vscode-theia-extension

@JonasHelming , two things:

• This is the example I mentioned in the dev call a few weeks back, I intend to add it to a new tips area on the website
• I'm happy to donate this repo to eclipse-theia if wanted or shall I leave it where it is?