diff --git a/docs/topics/installing-vs-code-extension.adoc b/docs/topics/installing-vs-code-extension.adoc deleted file mode 100644 index 0b10fd04..00000000 --- a/docs/topics/installing-vs-code-extension.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/vsc-extension-guide/master.adoc - -:_content-type: PROCEDURE -[id="installing-vs-code-extension_{context}"] -= Installing the {ProductShortName} extension for Visual Studio Code - -You can install the {ProductShortName} extension for Visual Studio Code (VS Code). - -.Prerequisites -include::snippet_jdk-hardware-mac-prerequisites.adoc[] - -.Procedure - -. Set the environmental variable `JAVA_HOME`: -+ -[source, terminal,subs="attributes+"] ----- -$ export JAVA_HOME=jdk11 ----- - -. In VS Code, click the *Extensions* icon on the Activity bar to open the *Extensions* view. -. Enter `{ProductName}` in the Search field. -. Select the *{ProductName}* extension and click *Install*. -+ -The {ProductShortName} extension icon (image:vs_extension_icon.png[{ProductShortName} code extension]) is displayed on the Activity bar. diff --git a/docs/topics/vs-code-extension-interface.adoc b/docs/topics/vs-code-extension-interface.adoc deleted file mode 100644 index ab5a359d..00000000 --- a/docs/topics/vs-code-extension-interface.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/vsc-extension-guide/master.adoc - -:_content-type: CONCEPT -[id="vs-code-extension-interface_{context}"] -= {ProductShortName} extension interface - - - -The interface of the {ProductName} ({ProductShortName}) extension is designed to make it easier for you to find information and perform actions: - -* In the left pane, you can see a directory tree named *Analysis Results* with a report icon at its top. You can click the icon to open the {ProductShortName} report in your browser. Beneath the report icon are the other elements of the tree: the applications analyzed by {ProductShortName}, the rulesets used, and the issues discovered by the analysis. -* In the upper right pane, you can configure an analysis. -* In the lower right pane, you can see the settings of the configuration, including source, target, and advanced options. You can view the progress of an analysis in this pane. When the analysis is completed, you can click the *Open Report* button to open the {ProductShortName} report, which describes any issues you need to address before you migrate or modernize your application. For more information, see link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] in the _{UserCLIBookName}_. - -.{ProductShortName} extension interface - -ifdef::mta[] - -endif::[] - -ifdef::mtr[] -image::mtr-extension-interface.png[{ProductShortName} extension interface] -endif::[] diff --git a/docs/topics/vs-code-extension-resolving-issues.adoc b/docs/topics/vs-code-extension-resolving-issues.adoc deleted file mode 100644 index 8f52824d..00000000 --- a/docs/topics/vs-code-extension-resolving-issues.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/vsc-extension-guide/master.adoc - -:_content-type: PROCEDURE -[id="vs-code-extension-resolving-issues_{context}"] -= Resolving issues - -You can resolve issues by editing the code of a file with a hint - - -//// - == Using a Quick Fix - -You can use a Quick Fix automatic code replacement to save time and ensure consistency in resolving repetitive issues. - -.Procedure - -. In the left pane, right-click an issue that has the Quick Fix icon (image:vs_optional.png[Optional or Quick Fix]) and select *Preview Quick Fix*. -. To accept the suggested fix, right-click the issue again and select *Apply Quick Fix.* -. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. -//// - -== Editing the code of a file - -You can edit the file of a project imported to VS Code. - -.Procedure - -. In the left pane, right-click an issue and select *Open Code*. -. Make any changes needed to the code and save the file. -. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. diff --git a/docs/topics/vs-code-extension-reviewing-issues.adoc b/docs/topics/vs-code-extension-reviewing-issues.adoc deleted file mode 100644 index cb91bf62..00000000 --- a/docs/topics/vs-code-extension-reviewing-issues.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/vsc-extension-guide/master.adoc - -:_content-type: PROCEDURE -[id="vs-code-extension-reviewing-issues_{context}"] -= Reviewing issues - -You can use the {ProductShortName} extension icons to prioritize issues based on their severity. - -.Procedure - -. Select a run configuration directory on the left pane. -. Expand its folders to view the *Hints* generated for each application file. -. Select a hint to view the source code. -. Right-click a hint and select *View Details* to view the Rule ID and other information. -. Prioritize issues based on the following icons, which are displayed next to each hint: - -** image:vs_mandatory.png[Mandatory] : The issue must be fixed for a successful migration. -** image:vs_potential.png[Warning] : The issue might need to be addressed during migration. diff --git a/docs/topics/vs-code-extension-run-configuration.adoc b/docs/topics/vs-code-extension-run-configuration.adoc deleted file mode 100644 index de677ed9..00000000 --- a/docs/topics/vs-code-extension-run-configuration.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/vsc-extension-guide/master.adoc - -:_content-type: PROCEDURE -[id="vs-code-extension-run-configuration_{context}"] -= Configuring a run configuration - -You can configure multiple run configurations to run against each project you import to VS Code. - -.Prerequisites - -* `{mta-cli}` executable installed. You can download the `{mta-cli}` executable from link:{DevDownloadPageURL}[{LC_PSN} download]. - -.Procedure - -. In *Extensions* view, click the {ProductName} icon (image:vs_extension_icon.png[{ProductShortName} code extension]) on the Activity bar. -. Click the *+* (plus sign) next to *{ProductName}* to add a run configuration. -. Complete the following configuration fields: - -** *Name*: Enter a meaningful name for the analysis configuration or accept the default. - -** *cli*: Enter the path to the cli executable. For example: `$HOME/{mta-cli}-{ProductDistributionVersion}/bin/{mta-cli}`. - -** *Input*: Set to the path of the project that you have open within your IDE by clicking *Add* and doing one of the following: - -*** Enter the input file or directory and press Enter. -*** Click *Open File Explorer* and select the directory. - -** *Target*: Select one or more target migration paths. - -. Right-click the run configuration and select *Run*. -+ -When the analysis is completed, you can click the *Open Report* button to open the {ProductShortName} report, which describes any issues you need to address before you migrate or modernize your application. For more information, see link:{ProductDocUserGuideURL}#review-reports_cli-guide[Reviewing the reports] in the _{UserCLIBookName}_. diff --git a/docs/topics/vscode/con_intro-to-vscode-for-mta.adoc b/docs/topics/vscode/con_intro-to-vscode-for-mta.adoc new file mode 100644 index 00000000..40280b6a --- /dev/null +++ b/docs/topics/vscode/con_intro-to-vscode-for-mta.adoc @@ -0,0 +1,29 @@ +:_newdoc-version: 2.18.5 +:_template-generated: 2025-07-21 +:_mod-docs-content-type: CONCEPT + +[id="intro-to-vscode-for-mta_{context}"] += Introduction to the {ProductShortName} extension for Microsoft Visual Code + +You can migrate and modernize applications by using the {ProductName} ({ProductShortName}) {AddonType} for {IDEName}. + +The {ProductShortName} {AddonType} can perform the following actions: + +* Analyze your projects with customizable rulesets. +* Mark issues in the source code. +* Provide guidance to fix the issues. +* Perform automatic code replacement, if possible. + +ifdef::vsc-extension-guide[] +The {ProductShortName} extension is also compatible with Visual Studio Codespaces, the Microsoft cloud-hosted development environment. +endif::[] + +ifdef::idea-plugin-guide[] +The {AddonType} supports both the Community Edition and the Ultimate version of {IDEName}. +endif::[] + + +// This module can be reused in the following files, if needed: +// +// * docs/intellij-idea-plugin-guide/master.adoc +// * docs/eclipse-code-ready-guide/master.adoc \ No newline at end of file diff --git a/docs/topics/vscode/con_vscode-extension-interface.adoc b/docs/topics/vscode/con_vscode-extension-interface.adoc new file mode 100644 index 00000000..f17e25f9 --- /dev/null +++ b/docs/topics/vscode/con_vscode-extension-interface.adoc @@ -0,0 +1,16 @@ +:_mod-docs-content-type: CONCEPT +[id="vscode-extension-interface_{context}"] += {ProductShortName} Visual Studio Code extension interface + +The interface of the {ProductName} ({ProductShortName}) extension for Visual Studio Code is designed to make it easier for you to find information and perform the required actions: + +* In the left pane, you can see the *Analysis Results* directory tree that includes the following elements: + +** A report icon. You can click the icon to open the {ProductShortName} report in your browser. +** The applications analyzed by {ProductShortName}. +** The rulesets used for the analysis. +** The issues discovered by the analysis. + +* In the upper right pane, you can configure an analysis. +* In the lower right pane, you can see the settings of the configuration, including source, target, and advanced options. You can view the progress of an analysis in this pane. When the analysis is completed, you can click the *Open Report* button to open the {ProductShortName} report, which describes any issues you need to address before you migrate or modernize your application. For more information, see link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.3/html-single/cli_guide/index#reviewing-analysis-reports_cli-guide[Reviewing an analysis report]. + diff --git a/docs/topics/vscode/images b/docs/topics/vscode/images new file mode 120000 index 00000000..e4c5bd02 --- /dev/null +++ b/docs/topics/vscode/images @@ -0,0 +1 @@ +../images/ \ No newline at end of file diff --git a/docs/topics/configuring-kantra-directory.adoc b/docs/topics/vscode/proc_configuring-kantra-directory.adoc similarity index 78% rename from docs/topics/configuring-kantra-directory.adoc rename to docs/topics/vscode/proc_configuring-kantra-directory.adoc index 3a45aeeb..e6f6c831 100644 --- a/docs/topics/configuring-kantra-directory.adoc +++ b/docs/topics/vscode/proc_configuring-kantra-directory.adoc @@ -4,32 +4,33 @@ [id="configuring-kantra-directory_{context}"] = Configuring the .kantra directory - + +[role="_abstract"] Starting from {ProductFullName} 7.2.0, you can perform an application analysis in the containerless mode. Before running the analysis, you must create and configure the `.kantra` directory. .Prerequisites -* You installed the {ProductShortName} extension version 7.2.0 or later on your system. For more information, see xref:installing-vs-code-extension_vsc-extension-guide[Installing the MTA extension for Visual Studio Code]. +* You installed the {ProductShortName} extension version 7.2.0 or later on your system. For more information, see xref:installing-vscode-extension_vsc-extension-guide[Installing the {ProductShortName} extension for Visual Studio Code]. * You installed the {ProductShortName} distribution version 7.2.0 or later. For more information, see link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.2/html/cli_guide/installing_and_running_the_cli#installing-downloadable-cli-zip_cli-guide[Installing the CLI .zip file]. .Procedure . Create a directory named `.kantra` in your `$HOME` directory: + -[source, terminal,subs="attributes+"] ----- -$ mkdir ~/.kantra/ ----- +[subs="+quotes"] +.... +$ *mkdir ~/.kantra/* +.... . Move all the files from the link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.2/html/cli_guide/installing_and_running_the_cli#installing-downloadable-cli-zip_cli-guide[extracted {ProductShortName} directory], except the `mta-cli` binary, into the `~/.kantra` directory. + -[source, terminal,subs="attributes+"] ----- -$ mv !(mta-cli) ~/.kantra/ ----- +[subs="+quotes"] +.... +$ *mv !(mta-cli) ~/.kantra/* +.... .Verification -* Verify that you created and configured the `.kantra` directory correctly by running the application analysis. For more information, see xref:analyzing-projects-with-vs-code-extension_vsc-extension-guide[Analyzing your projects with the MTA extension]. - +* Verify that you created and configured the `.kantra` directory correctly by running the application analysis. For more information, see xref:vscode-analyzing-application_vsc-extension-guide[Configuring and running an application analysis]. + diff --git a/docs/topics/vscode/proc_installing-vscode-extension.adoc b/docs/topics/vscode/proc_installing-vscode-extension.adoc new file mode 100644 index 00000000..17183153 --- /dev/null +++ b/docs/topics/vscode/proc_installing-vscode-extension.adoc @@ -0,0 +1,33 @@ +:_mod-docs-content-type: PROCEDURE +[id="installing-vscode-extension_{context}"] += Installing the {ProductShortName} extension for Visual Studio Code + +[role="_abstract"] +You can install the {ProductShortName} extension for Visual Studio Code (VS Code). + +.Prerequisites + +* You installed the Java Development Kit (JDK). {ProductShortName} supports the following JDKs: + +** Oracle JDK 17 or later +** Eclipse Temurin™ JDK 17 or later +** OpenJDK 17 or later + +* You have 8 GB of RAM available. + +* For macOS installation, you have the value of `maxproc` set to `2048` or greater. + +.Procedure + +. Set the `JAVA_HOME` environmental variable: ++ +[subs="+quotes"] +.... +$ *export JAVA_HOME=jdk11* +.... + +. In VS Code, click the *Extensions* icon on the *Activity* bar to open the *Extensions* view. +. Enter `{ProductName}` in the Search field. +. Select the *{ProductName}* extension and click *Install*. ++ +The {ProductShortName} extension icon (image:vs_extension_icon.png[{ProductShortName} code extension]) is displayed on the Activity bar. diff --git a/docs/topics/vscode/proc_vscode-analyzing-application.adoc b/docs/topics/vscode/proc_vscode-analyzing-application.adoc new file mode 100644 index 00000000..caf2bd2f --- /dev/null +++ b/docs/topics/vscode/proc_vscode-analyzing-application.adoc @@ -0,0 +1,34 @@ +:_mod-docs-content-type: PROCEDURE +[id="vscode-analyzing-application_{context}"] += Configuring and running an application analysis + +[role="_abstract"] +To analyze an application with the {ProductShortName} extension for Visual Studio Code, you must create a run configuration first. You can configure multiple run configurations to run against each project you import to Visual Studio Code. + +.Prerequisites + +* You installed the `{mta-cli}` executable. You can download `{mta-cli}` from the link:https://developers.redhat.com/products/mta/download[{ProductShortName} download page]. + +.Procedure + +. In *Extensions* view, click the {ProductName} icon (image:vs_extension_icon.png[{ProductShortName} code extension]) on the *Activity* bar. +. Click the plus sign (*+*) next to *{ProductName}* to add a run configuration. +. Specify the following configuration fields: + +** *Name*: Enter a name for the analysis configuration or accept the default suggestion. + +** *cli*: Enter the path to the `{mta-cli}` executable, for example: `$HOME/{mta-cli}-{ProductDistributionVersion}/bin/{mta-cli}`. + +** *Input*: Set to the path of the project that you have open within your IDE: + +... Click *Add*. +... Perform one of the following actions: + +**** Enter the input file or directory and press *Enter*. +**** Click *Open File Explorer* and select the directory. + +** *Target*: Select one or more target migration paths. + +. Right-click the run configuration and select *Run*. ++ +When the analysis is completed, you can click the *Open Report* button to open the {ProductShortName} report, which describes the issues you need to address before you migrate or modernize your application. For more information, see link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.3/html-single/cli_guide/index#reviewing-analysis-reports_cli-guide[Reviewing an analysis report]. diff --git a/docs/topics/vscode/proc_vscode-reviewing-and-resolving-issues.adoc b/docs/topics/vscode/proc_vscode-reviewing-and-resolving-issues.adoc new file mode 100644 index 00000000..8d091efa --- /dev/null +++ b/docs/topics/vscode/proc_vscode-reviewing-and-resolving-issues.adoc @@ -0,0 +1,36 @@ +:_mod-docs-content-type: PROCEDURE +[id="vscode-reviewing-and-resolving-issues_{context}"] += Reviewing and resolving migration issues + +[role="_abstract"] +You can use the {ProductShortName} extension icons to prioritize issues based on their severity. + +.Procedure + +. Select a run configuration directory on the left pane. +. Expand its folders to view the *Hints* generated for each application file. +. Select a hint to view the source code. +. Right-click a hint and select *View Details* to view the Rule ID and other information. +. Prioritize issues based on the following icons, which are displayed next to each hint: + +** image:vs_mandatory.png[Mandatory]: You must fix the issue for a successful migration. +** image:vs_potential.png[Warning]: You might need to address the issue during the migration. + +. Resolve issues by editing the code of a file with a hint: + +.. In the left pane, right-click an issue and select *Open Code*. +.. Make any changes needed to the code and save the file. +.. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. + +//// + == Using a Quick Fix + +You can use a Quick Fix automatic code replacement to save time and ensure consistency in resolving repetitive issues. + +.Procedure + +. In the left pane, right-click an issue that has the Quick Fix icon (image:vs_optional.png[Optional or Quick Fix]) and select *Preview Quick Fix*. +. To accept the suggested fix, right-click the issue again and select *Apply Quick Fix*. +. Optional: Right-click the issue and select *Mark as Complete* or *Delete*. +//// + diff --git a/docs/vs-code-extension-guide/assemblies b/docs/vs-code-extension-guide/assemblies new file mode 120000 index 00000000..51bb5102 --- /dev/null +++ b/docs/vs-code-extension-guide/assemblies @@ -0,0 +1 @@ +../../assemblies/ \ No newline at end of file diff --git a/docs/vs-code-extension-guide/master-docinfo.xml b/docs/vs-code-extension-guide/master-docinfo.xml index 1d385324..d3790176 100644 --- a/docs/vs-code-extension-guide/master-docinfo.xml +++ b/docs/vs-code-extension-guide/master-docinfo.xml @@ -1,9 +1,9 @@ Visual Studio Code Extension Guide {DocInfoProductName} {DocInfoProductNumber} -Identify and resolve migration issues by analyzing your applications with the {ProductName} extension for Visual Studio Code. +Using the {ProductName} extension for Visual Studio Code to identify and resolve migration issues - This guide describes how to use the {ProductName} extension for Visual Studio Code to accelerate large-scale application modernization efforts across hybrid cloud environments on Red Hat OpenShift.. + You can use the {ProductName} extension for Visual Studio Code to accelerate large-scale application modernization efforts across hybrid cloud environments on Red Hat OpenShift. You can analyze your applications and identify and resolve issues to prepare these applications for a successful migration. Red Hat Customer Content Services diff --git a/docs/vs-code-extension-guide/master.adoc b/docs/vs-code-extension-guide/master.adoc index 24bafd47..8548fc9f 100644 --- a/docs/vs-code-extension-guide/master.adoc +++ b/docs/vs-code-extension-guide/master.adoc @@ -9,44 +9,28 @@ :IDEName: Microsoft Visual Studio Code :mta: include::topics/templates/document-attributes.adoc[] -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY = Visual Studio Code Extension Guide //Inclusive language statement include::topics/making-open-source-more-inclusive.adoc[] -== Introduction - -// About the VS Code extension -include::topics/about-ide-addons.adoc[leveloffset=+2] - -// About {ProductName} -include::topics/mta-what-is-the-toolkit.adoc[leveloffset=+2] - -// Install the extension -include::topics/installing-vs-code-extension.adoc[leveloffset=+1] - - -// Create and configure .kantra for the analysis -include::topics/configuring-kantra-directory.adoc[leveloffset=+1] + +include::topics/vscode/con_intro-to-vscode-for-mta.adoc[leveloffset=+1] + +// Remove after other files that include this modules use the new topics/vscode/con_intro-to-vscode-for-mta.adoc module instead!!! +// include::topics/about-ide-addons.adoc[leveloffset=+2] -[id="analyzing-projects-with-vs-code-extension_{context}"] -== Analyzing your projects with the {ProductShortName} extension +include::topics/vscode/proc_installing-vscode-extension.adoc[leveloffset=+1] -You can analyze your projects with the {ProductShortName} extension by creating a run configuration and running an analysis. +include::topics/vscode/proc_configuring-kantra-directory.adoc[leveloffset=+1] -include::topics/vs-code-extension-interface.adoc[leveloffset=+2] +include::topics/vscode/con_vscode-extension-interface.adoc[leveloffset=+1] -include::topics/vs-code-extension-run-configuration.adoc[leveloffset=+2] +include::topics/vscode/proc_vscode-analyzing-application.adoc[leveloffset=+1] -[id="reviewing-and-resolving-issues-with-vs-code-extension_{context}"] -== Reviewing and resolving migration issues - -You can review and resolve migration issues identified by the {ProductShortName} extension in the left pane. - -include::topics/vs-code-extension-reviewing-issues.adoc[leveloffset=+2] +include::topics/vscode/proc_vscode-reviewing-and-resolving-issues.adoc[leveloffset=+1] -include::topics/vs-code-extension-resolving-issues.adoc[leveloffset=+2] :!vsc-extension-guide: