Document Liberty Tools for MVP

[dmuelle]

We need an overview page for the new Liberty Tools for Eclipse, VS Code, and Intellij.

• most likely in the basics section of the docs nav
• The page should explain the benefits of using the tools in your chosen IDE by giving a high-level overview of the functions:
  • dev mode
  • debug
  • content assist for liberty config
  • content assist for MP
• link out to the individual GitHub repos for more details, installation, etc.
  • https://openliberty.io/blog/2022/08/01/liberty-tools-eclipse.html
  • https://github.com/OpenLiberty/liberty-tools-vscode
  • https://github.com/OpenLiberty/liberty-tools-intellij
• link to marketplaces to obtain tools
  • Open Liberty Tools for VS Code from the Visual Studio Marketplace.
  • Open Liberty Tools for IntelliJ from the JetBrains Marketplace.
  • need marketplace link for eclipse
• Create links to the page from relevant docs incl dev mode, MP overview, and the Website getting started page.
• as part of this issue, review the documentation in the individual GitHub repos to optimize the content and provide a consistent experience across all three. Who is the contact for these pages?
• also review the release blog post

Planned MVP Ga is December 9th. Doc will publish with 22.0.0.13

[yeekangc]

Need to link out to marketplace entries for the tools as well.

[dmuelle]

comment from slack discussion: Does Liberty Tools support EE8 and MP4? Determine by pom.xml or server.xml?

This should be at the top of our doc.
I don't believe we offer any assistance with EE 8...
@Kathryn Kodama
or
@tcrawford
please correct me.
For MP 4, since it's the same classes as MP 3, I believe you can make use of the LS, as long as you stick to the MP 3 subset.

[kinueng]

The openliberty.io work item for the new IDE tools section

[kathrynkodama]

@cherylking Right, it does not apply to the Jakarta and MP language support. They will provide support on any Java file that detects usage of the Jakarta EE and MP APIs

[dmuelle]

To use Liberty Tools with dev mode, your project must specify the Liberty Maven plug-in or the Liberty Gradle plug-in in the project pom.xl or build.gradle file. A minimum level of 3.7.1 for the Liberty Maven plug-in or 3.5.1 for the Liberty Gradle plug-in is recommended.

Language support features are available for MicroProfile 3.0 and 4.0 APIs, Jakarta EE 9.x APIs, and select Liberty configuration and Java files.

I guess we could say something like

To use the full set of Liberty Tools functions for dev mode, your project must specify...

[scottkurz]

OK, I'm a bit late to the game, sorry about that. Some of this has been said already but I'm basing my comments on the latest draft server even if there's some overlap

1. pom.xl => pom.xml (this still appears twice)
2. plug-in? I see this is indeed what this doc uses....it's just weird since Maven/Gradle generally use "plugin" and only Eclipse uses this "plug-in" but OK.
3. Liberty Tools singular vs. plural - I see we had a bunch of discussion already. To me it looks weird to see it plural...most of the time users will encounter it as a singular entity in their IDE and not care about our collective effort.. but.. I'm late to the party and it doesn't look awful as a plural.
4. In the "Minimum Requirements" sec. when we see the sentence:
   Language support features are available for MicroProfile 3.0 and 4.0 APIs, Jakarta EE 9.x APIs, and select Liberty configuration and Java files we just read essentially the same thing in the very first section so maybe could delete.
5. "With a just few clicks" => "With just a few clicks"
6. "Virtual Studio Code CodeLens support " you must have meant "Visual Studio Code CodeLens".... or is just "CodeLens" enough? I might read this and think it doesn't apply to Eclipse....but if this is the better common name fine.
7. The Liberty Tools Eclipse IDE Eclipse Marketplace link is now live at:
   Liberty Tools Eclipse link: https://marketplace.eclipse.org/content/liberty-tools

[scottkurz]

One more detail:

These features are available for the following Liberty configuration files
 ...
    Any XML files that contain the server root element and exist in the src/main/liberty/config, configDropins/overrides, configDropins/defaults, usr/shared/config, or usr/servers directory

I don't think that accurately describes the current story....e.g. a src/main/liberty/config/my.xml won't get the LCLS XML support. @cherylking correct me if I'm wrong. Maybe we could just say less and it'd be close enough. Was there already a comment on this?

[cherylking]

I don't think that accurately describes the current story....e.g. a src/main/liberty/config/my.xml won't get the LCLS XML support. @cherylking correct me if I'm wrong. Maybe we could just say less and it'd be close enough. Was there already a comment on this?

I think it will get support. I will have to verify, but we look for other xml files in the pre-defined config locations for Liberty in addition to any xml file <include> from the server.xml.

[dmuelle]

Thanks for reviewing @scottkurz - I made the following changes-

1. fixed instances of pom.xl
2. "plug-in" - this is the spelling IBM terminology recommends and also what we use elsewhere in the Open Liberty docs
3. Liberty Tools singular vs. plural- I'm still not 100% sold on them being plural- though I agree with Cheryl that having them singular was awkward in parts of the doc.
4. removed redundant language support info from the minimum requirements- its mentioned in the intro and detailed in the language support section. Also not technically a minimum requirement for using the tools
5. fixed ""With a just few clicks"
6. Changed VS CodeLens to be just CodeLens- I didn't realize this was available in eclipse as most references on the web only mention vs code. Is it valid for Intellij?
7. added eclipse marketplace link

I left the supported files list as is based on Cheryl's response- can update if needed.

[cherylking]

@dmuelle Maybe it would be safer for now to take out the line about the additional XML files in those config folders. We can add it later once we figure out whatever bug we have in that section of code.

[cherylking]

@dmuelle After some testing, I think the line just needs to be altered slightly from:

    Any XML files that contain the server root element and exist in the src/main/liberty/config, configDropins/overrides, configDropins/defaults, usr/shared/config, or usr/servers directory

to

    Any XML files that contain the server root element and exist in the configDropins/overrides, configDropins/defaults, usr/shared/config, or usr/servers directory

[dmuelle]

@cherylking - updated Liberty config XML file list
https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/develop-liberty-tools.html#_liberty_configuration_files

[dmuelle]

Thanks to all for your work on the overview doc for the early release refresh, it is now published at

https://openliberty.io/docs/latest/develop-liberty-tools.html

I'm going to keep this issue open at the moment to track related ID updates in the various Git repos. Here is the progress on those so far:

IntelliJ and VS Code: edited and published the Git docs, including the README, user guide, Developing, Contributing
Eclipse: awaiting updates
LCLS: Docs edited and updated
LSP4Jarkarta: Docs edited and updated

We can also use this issue to track any changes needed between the early release and GA

[dmuelle]

ID work for GA is tracked in #6403, closing this issue