Merge pull request eclipse-che#763 from MichalMaler/i1145-Che-Theia_I…

…DE_basics

Che Theia IDE basics

Signed-off-by: Michal Maléř <mmaler@redhat.com>

src/main/_data/sidebars/che_7_docs.yml

@@ -27,9 +27,9 @@ entries:
   - title: End-user Guide
     output: web
     folderitems:
-    #- title: Che-Theia IDE basics
-      #url: che-theia-ide-basics.html
-      #output: web
+    - title: Che-Theia IDE basics
+      url: che-theia-ide-basics.html
+      output: web
     - title: Using developer workspaces
       url: using-developer-environments-workspaces.html
       output: web

src/main/pages/che-7/end-user-guide/assembly_che-theia-ide-basics.adoc

@@ -1,81 +1,30 @@
 ---
 title: Che-Theia IDE basics
-keywords: 
+keywords:
 tags: []
 sidebar: che_7_docs
 permalink: che-7/che-theia-ide-basics.html
 folder: che-7/end-user-guide
-summary: 
+summary:
 ---
 
 :parent-context-of-che-theia-ide-basics: {context}
 
 [id='che-theia-ide-basics_{context}']
 = Che-Theia IDE basics
-:context: che-theia-ide-basics
-
-This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. Can include more than one paragraph. Consider using the information from the user story.
-
-.Prerequisites
-
-* A bulleted list of conditions that must be satisfied before the user starts following this assembly.
-* You can also link to other modules or assemblies the user must follow before starting this assembly.
-* Delete the section title and bullets if the assembly has no prerequisites.
-
-// include::modules/subsystem/proc_doing_one_procedure.adoc[leveloffset=+1]
-
-== Navigating the Che-Theia user interface
-
-
-
-== Files and projects
-
-
-
-== Editing code and code assistance
-
-
-
-== Key bindings
-
-
-
-== Searching
-
-
 
-== Commands
-
-
-
-== Debugging
-
-
-
-== Testing
-
-
-
-== Version control
-
-
-
-== Integrated terminal
-
-
-
-== Languages
-
-
-
-== SSH
+:context: che-theia-ide-basics
 
+include::assembly_defining-custom-commands-for-che-theia.adoc[leveloffset=+1]
 
+include::assembly_version-control.adoc[leveloffset=+1]
 
+////
 .Related information
 
 * A bulleted list of links to other material closely related to the contents of the concept module.
 * For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+////
 
 :context: {parent-context-of-che-theia-ide-basics}

src/main/pages/che-7/end-user-guide/assembly_defining-custom-commands-for-che-theia.adoc

@@ -0,0 +1,93 @@
+:parent-context-of-defining-custom-commands-for-che-theia: {context}
+
+// che-theia-ide-basics
+
+[id='defining-custom-commands-for-che-theia_{context}']
+= Defining custom commands for Che-Theia
+
+:context: defining-custom-commands-for-che-theia
+
+The Che-Theia IDE allows users to define custom commands in a devfile that are then available when working in a workspace.
+
+The following is an example of the `commands` section of a devfile.
+
+[source,yaml]
+----
+commands:
+- name: theia:build
+  actions:
+  - type: exec
+    component: che-dev
+    command: >
+              yarn
+    workdir: /projects/theia
+- name: run
+  actions:
+  - type: vscode-task
+    referenceContent: |
+            {
+             "version": "2.0.0",
+             "tasks":
+             [
+              {
+               "label": "theia:watch",
+                "type": "shell",
+                "options": {"cwd": "/projects/theia"},
+                "command": "yarn",
+                "args": ["watch"]
+              }
+             ]
+            }
+- name: debug
+  actions:
+  - type: vscode-launch
+    referenceContent: |
+            {
+             "version": "0.2.0",
+             "configurations": [
+              {
+               "type": "node",
+               "request": "attach",
+               "name": "Attach by Process ID",
+               "processId": "${command:PickProcess}"
+              }
+             ]
+            }
+----
+
+Che commands:: `theia:build`
++
+* The `exec` type implies that the Che runner is used for command execution. The user can specify the component in whose container the command is executed.
+* The `command` field contains the command line for execution.
+* The `workdir` is the working directory in which the command is executed.
+
+Visual Studio Code (VS Code) tasks:: `run`
++
+* The type is `vscode-task`.
+* For this type of command, the `referenceContent` field must contain content with task configurations in the VS Code format.
+* For more information about VS Code tasks, see the link:https://code.visualstudio.com/docs/editor/tasks[Task section at Visual Studio User Guide page].
+
+VS Code launch configurations:: `debug`
++
+* The type is `vscode-launch`.
+* It contains the launch configurations in the VS Code format.
+* For more information about VS Code launch configurations, see the link:https://code.visualstudio.com/docs/editor/debugging#_launch-configurations[Debugging section at the Visual Studio documentation page].
+
+For a list of available tasks and launch configurations, see the `tasks.json` and the `launch.json` configuration files in the `/workspace/.theia` directory where the configuration from the devfile is exported to.
+
+include::con_che-theia-task-types.adoc[leveloffset=+1]
+
+include::proc_running-and-debugging.adoc[leveloffset=+1]
+
+include::proc_editing-a-task-and-a-launch-configuration.adoc[leveloffset=+1]
+
+////
+[id='related-information-{context}']
+== Related information
+
+* A bulleted list of links to other material closely related to the contents of the concept module.
+* For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+////
+
+:context: {parent-context-of-defining-custom-commands-for-che-theia}

src/main/pages/che-7/end-user-guide/assembly_version-control.adoc

@@ -0,0 +1,27 @@
+:parent-context-of-version-control: {context}
+
+// che-theia-ide-basics
+
+[id='version-control_{context}']
+= Version Control
+
+:context: version-control
+
+Eclipse Che natively supports the link:https://code.visualstudio.com/docs/editor/versioncontrol#_scm-providers[VS Code SCM model]. By default, Eclipse Che includes the native link:https://code.visualstudio.com/docs/editor/versioncontrol#_git-support[VS Code Git extension] as an Source Code Management (SCM) provider.
+
+include::proc_accessing-a-git-repository-via-https.adoc[leveloffset=+1]
+
+include::proc_accessing-a-git-repository-via-ssh.adoc[leveloffset=+1]
+
+include::proc_managing-pull-requests-using-the-github-pr-plug-in.adoc[leveloffset=+1]
+
+////
+[id='related-information-{context}']
+== Related information
+
+* A bulleted list of links to other material closely related to the contents of the concept module.
+* For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+////
+
+:context: {parent-context-of-version-control}

src/main/pages/che-7/end-user-guide/con_che-theia-task-types.adoc

@@ -0,0 +1,21 @@
+// defining-custom-commands-for-che-theia
+
+[id="che-theia-task-types_{context}"]
+= Che-Theia task types
+
+There are two types of tasks in a devfile: tasks in the VS Code format and Che commands. Tasks from the devfile are copied to the configuration file when the workspace is started. Depending on the type of the task, the task is then available for running:
+
+* Che commands: From the *Terminal -> Run Task* menu in the *configured tasks* section, or from the *My Workspace* panel
+
+* Tasks in the VS Code format: From the *Run Tasks* menu
+
+To run the task definitions provided by plug-ins, select the *Terminal -> Run Task* menu option. The tasks are placed in the *detected tasks* section.
+
+////
+[discrete]
+== Additional resources
+
+* A bulleted list of links to other material closely related to the contents of the concept module.
+* For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+////

src/main/pages/che-7/end-user-guide/proc_accessing-a-git-repository-via-https.adoc

@@ -0,0 +1,20 @@
+// version-control
+
+[id="accessing-a-git-repository-via-https_{context}"]
+= Accessing a Git repository via HTTPS
+
+.Procedure
+
+To clone a repository using HTTPS:
+
+. Use the link:https://code.visualstudio.com/docs/editor/versioncontrol#_cloning-a-repository[clone] command provided by the `vscode` Git extension.
+
+NOTE: Alternatively, use the native *Git* commands in the terminal to clone a project.
+
+////
+.Additional resources
+
+* A bulleted list of links to other material closely related to the contents of the procedure module.
+* For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+////

src/main/pages/che-7/end-user-guide/proc_accessing-a-git-repository-via-ssh.adoc

@@ -0,0 +1,44 @@
+// version-control
+
+[id="accessing-a-git-repository-via-ssh_{context}"]
+= Accessing a Git repository via SSH
+
+
+.Prerequisites
+
+* SSH key pair generated
+
+
+== Generating an SSH key
+
+To generate an SSH key pair:
+
+. Run the *SSH: generate key pair* command, or, to generate a key that will work only with a particular Git provider, run *SSH: generate key pair for particular host*.
+. After the key is generated, click the btn:[View] button and copy the public key from the editor.
+. Add the public key to the Git provider.
+
+
+== Adding the associated public key to a repository or account on GitHub
+
+To add the associated public key to a repository or account on GitHub:
+
+. Navigate to link:https://github.com[github.com].
+. Click the drop-down arrow next to the user icon in the top-right corner.
+. Click *Settings -> SSH and GPG keys* and then click the btn:[New SSH key] button.
+. In the *Title* field, type a title for the key, and in the *Key* field, paste the public key copied from Che.
+. Click the btn:[Add SSH key button].
++
+image::ide/che-theia-basics-ssh.png[]
+
+
+== Adding the associated public key to a Git repository or account on GitLab
+
+To add the associated public key to a Git repository or account on GitLab:
+
+. Navigate to link:https://gitlab.com[gitlab.com].
+. Click the user icon in the top-right corner of the window.
+. Click *Settings -> SSH Keys*.
+. In the *Title* field, type a title for the key and in the *Key* field, paste the public key copied from Che.
+. Click the btn:[Add key] button.
++
+image::ide/che-theia-basics-ssh-keys.png[link="{imagesdir}/ide/che-theia-basics-ssh-keys.png"]

src/main/pages/che-7/end-user-guide/proc_editing-a-task-and-a-launch-configuration.adoc

@@ -0,0 +1,24 @@
+// defining-custom-commands-for-che-theia
+
+[id="editing-task-and-launch-configuration_{context}"]
+= Editing task and launch configuration
+
+.Procedure
+
+To customize the configuration file:
+
+. Edit the `tasks.json` or `launch.json` configuration files.
+. Add new definitions to the configuration file or modify the existing ones.
++
+NOTE: The changes are stored in the configuration file.
+
+. To customize the task configuration provided by plug-ins, select the *Terminal -> Configure Tasks...* menu option, and choose the task to configure.
+. The configuration is then copied to the `tasks.json` file and is available for editing.
+
+////
+.Additional resources
+
+* A bulleted list of links to other material closely related to the contents of the concept module.
+* For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+////

src/main/pages/che-7/end-user-guide/proc_managing-pull-requests-using-the-github-pr-plug-in.adoc

@@ -0,0 +1,28 @@
+// version-control
+
+[id="managing-pull-requests-using-the-github-pr-plug-in_{context}"]
+= Managing pull requests using the GitHub PR plug-in
+
+To manage GitHub pull requests, the VS Code GitHub Pull Request plug-in is available in the list of plug-ins of the workspace.
+
+
+== Using the GitHub Pull Requests plug-in
+
+. Authenticate by running the *GitHub Pull Requests: Manually Provide Authentication Response* command and paste the GitHub token. 
+. Select the repository permissions when generating the token.
+
+
+== Creating a new pull request
+
+. Open the GitHub repository. To be able to execute remote operations, the repository must have a _remote_ with an SSH URL.
+. Checkout a new branch and make changes that you want to publish.
+. Run the *GitHub Pull Requests: Create Pull Request* command.
+
+////
+[discrete]
+== Additional resources
+
+* A bulleted list of links to other material closely related to the contents of the procedure module.
+* For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+////