oniro-ide-docs: Adding More Pages

Adding "Getting Started", "Code Editing", "Code Navigation", "Refactoring", and "Language Support" Signed-off-by: Mariz Samir Mounir Awad <[email protected]>
eclipse-oniro4openharmony · Feb 5, 2024 · bd7f1a6 · bd7f1a6
1 parent 7e4268f
commit bd7f1a6
Show file tree

Hide file tree

Showing 21 changed files with 264 additions and 14 deletions.
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -10,8 +10,10 @@ GEM
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
     ffi (1.16.3)
+    ffi (1.16.3-x64-mingw-ucrt)
     forwardable-extended (2.6.0)
     google-protobuf (3.25.1-arm64-darwin)
+    google-protobuf (3.25.1-x64-mingw-ucrt)
     google-protobuf (3.25.1-x86_64-linux)
     http_parser.rb (0.8.0)
     i18n (1.14.1)
@@ -64,16 +66,20 @@ GEM
     rexml (3.2.6)
     rouge (4.2.0)
     safe_yaml (1.0.5)
-    sass-embedded (1.69.5)
+    sass-embedded (1.69.5-arm64-darwin)
+      google-protobuf (~> 3.23)
+    sass-embedded (1.69.5-x64-mingw-ucrt)
+      google-protobuf (~> 3.23)
+    sass-embedded (1.69.5-x86_64-linux-gnu)
       google-protobuf (~> 3.23)
-      rake (>= 13.0.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
     unicode-display_width (2.5.0)
     webrick (1.8.1)
 
 PLATFORMS
   arm64-darwin-23
+  x64-mingw-ucrt
   x86_64-linux
 
 DEPENDENCIES

diff --git a/_config.yml b/_config.yml
@@ -18,3 +18,16 @@ nav_external_links:
     url: https://oniroproject.readthedocs.io/
     hide_icon: false
     opens_in_new_tab: false
+
+callouts:
+  warning:
+    title: Warning
+    color: red
+
+  note:
+    title: Note
+    color: purple
+
+  tip:
+    title: Tip
+    color: yellow
diff --git a/assets/images/Go.png b/assets/images/Go.png
diff --git a/assets/images/c-c++.png b/assets/images/c-c++.png
diff --git a/assets/images/create-project.png b/assets/images/create-project.png
diff --git a/assets/images/cs.png b/assets/images/cs.png
diff --git a/assets/images/extract-method.png b/assets/images/extract-method.png
diff --git a/assets/images/find-and-replace.png b/assets/images/find-and-replace.png
diff --git a/assets/images/go-to-symbol.png b/assets/images/go-to-symbol.png
diff --git a/assets/images/java.png b/assets/images/java.png
diff --git a/assets/images/js.png b/assets/images/js.png
diff --git a/assets/images/python.png b/assets/images/python.png
diff --git a/assets/images/rename-symbol.png b/assets/images/rename-symbol.png
diff --git a/ide-code-editing.md b/ide-code-editing.md
@@ -0,0 +1,29 @@
+---
+title: Code Editing
+layout: home
+nav_order: 3
+parent: Oniro IDE
+---
+
+## Keyboard Shortcuts
+Being able to keep your hands on the keyboard when writing code is crucial for high productivity. You can explore the different keyboard shortcuts by navigating to `File -> Preferences -> Keyboard Shortcuts` from the menu tab or clicking `Ctrl+Alt+,`.
+
+## Selection
+Different selection options can be explored from `Selection` in the menu tab. A few of the important ones are `Shift + Right/Left/Up/Down` for basic selection, `Ctrl + Shift + Right/Left`  for whole words selection, and column selection by placing the cursor in one corner and then holding `Shift+Alt` while dragging to the opposite corner.
+
+## Save & Auto Save
+To save a file press `Ctrl+S` or enable auto save from `File -> Auto Save` which will save your changes after a configured delay or when focus leaves the editor.
+
+## Find & Replace
+![Alt text](assets/images/find-and-replace.png)
+Press `Ctrl+F` to toggle the `Find` feature of the IDE, write the word or phrase you're searching for and press `Enter` or `Shift+Enter` to go up and down the results. As seen in the above there are several options to the search namely:
+
+1. **Match Case:** to find a word or phrase with the same case letters.
+2. **Match Whole Word:** to eliminate words or phrases that don't contain all the letters of each word from the results.
+3. **Use Regular Expression:** For an advanced search using [regular expresions](https://learn.microsoft.com/en-us/visualstudio/ide/using-regular-expressions-in-visual-studio?view=vs-2022).
+4. **Find in Selection:** to first select a piece of code and then search only within the selection.
+5. **Replace:** to replace each of the search results with the word or phrase in the *Replace* field.
+6. **Replace All:** to replace *all* of the search result with the word or phrase in the Replace field, all in one click.
+
+{: .tip }
+> To search multiple files at once press `Ctrl+Shift+F`.
diff --git a/ide-code-navigation.md b/ide-code-navigation.md
@@ -0,0 +1,34 @@
+---
+title: Code Navigation
+layout: home
+nav_order: 4
+parent: Oniro IDE
+---
+
+A dynamic combination between programming languages services and quick text editing gives Oniro IDE its power. In this topic we will give an overview of a few code navigation features which can be explored when you right click on a symbol (variable, function, method, class, etc.).
+
+## Go to Definition
+The "Go to Definition" feature is a code navigation tool that allows you to quickly navigate to the definition of a particular symbol in your codebase. This feature is commonly used to explore the implementation or declaration of functions, classes, variables, methods, and other code entities. You can do this by `Ctrl+Click` as with other IDEs or `Ctrl+F11`.
+
+## Go to Type Definition
+This feature specifically deals with navigating to the type definition of a symbol. It is useful in statically-typed languages where you might want to see the type information associated with a variable or entity.
+
+## Go to Symbol
+![Alt text](assets/images/go-to-symbol.png)
+This allows you to quickly navigate to symbols (ie. variables, functions, classes..etc) within your file.
+
+## Go to Implementations
+The "Go to Implementations" feature allows you to quickly jump to the implementations of a particular function, method, or interface in your codebase. This feature is particularly useful in languages that support interfaces, classes, or methods with multiple implementations.
+
+{:.tip}
+>  If you want to see all the places where a particular method or function is implemented, "Find All Implementations" is useful for a more comprehensive overview.
+
+
+## Find All References
+This is a code analysis tool that allows you to locate all occurrences or references to a particular symbol (variable, function, method, class, etc.) within your codebase. Its purpose is to provide developers with a comprehensive overview of where a specific symbol is used throughout their project.
+
+## Peek
+This is a special feature that allows developers to quickly view the definition or implementation of a symbol inline without navigating away from the current code file to avoid context switching.
+
+You can navigate between different references in the peeked editor and make quick edits right there.
+
diff --git a/ide-getting-started.md b/ide-getting-started.md
@@ -0,0 +1,65 @@
+---
+title: Getting Started
+layout: home
+nav_order: 1
+parent: Oniro IDE
+---
+## Installation
+Please make sure that your system follows the [Theia development prerequisites](https://github.com/eclipse-theia/theia/blob/master/doc/Developing.md#prerequisites).
+
+### Building
+You can build both browser and electron application by running the following script:
+```
+yarn
+yarn compile
+yarn download:plugins
+```
+
+### Running
+To start the browser application you just need to run:
+```
+yarn browser start
+```
+And similarly for the electron application:
+
+```
+yarn electron start
+```
+
+Watching
+To contiously compile the written TypeScript code, run the respective commands for your runtime:
+
+```
+yarn browser watch
+```
+Or
+
+```
+yarn electron watch
+```
+### Running in Docker container
+[Install docker](https://docs.docker.com/get-docker/).
+
+To create the docker image `oniro-ide`:
+
+```
+docker build -t oniro-ide .
+```
+To start the container `oniro-ide-container`:
+
+```
+docker run -dp 3000:3000 --name oniro-ide-container oniro-ide
+```
+When you open the browser at `http://localhost:3000/` you will see the browser version of the IDE.
+
+## Creating and Running a Project
+
+![create-project](assets/images/create-project.png)
+To create a new project navigate to `Project` from the menu tab and click `New Project`. From the pop-up window select the folder where you want to save your project and give your project a name. Finally select the hardware chip of your choice, click `Next` and `Finish`. This creates a new project workspace for your development.
+
+To open your project, navigate to `File -> Open...` from the menu tab, navigate to your project's location, and click `Open`. This will open your project as you can see down in the `Explorer`.
+
+From here on out you can [add files/folders using the `Explorer` pane](ide-user-interface.md/#explorer) or use tools such as [npm](https://www.npmjs.com/) package manager to help you create projects.
+
+{: .note }
+> So far you can develop projects in the IDE in a plethora of languages. However, building and running project is still under construction.
diff --git a/ide-language-support.md b/ide-language-support.md
@@ -0,0 +1,20 @@
+---
+title: Language Support
+layout: home
+nav_order: 7
+parent: Oniro IDE
+---
+
+As Oniro IDE is built using [Theia](https://theia-ide.org/docs/) which is heavily influenced by VS Code, the languages supported by the IDE are all of those supported by VS Code. Examples of such languages are:
+
+|:-------------|:-------------|:-------------|
+|[![Python](assets/images/python.png)**Python**](https://code.visualstudio.com/docs/languages/python)|[![Alt text](assets/images/c-c++.png)**C/C++**](https://code.visualstudio.com/docs/languages/cpp)|[![Alt text](assets/images/cs.png)**C#**](https://code.visualstudio.com/docs/languages/csharp)|
+|[![Alt text](assets/images/Go.png)**Go**](https://code.visualstudio.com/docs/languages/go)|[![Alt text](assets/images/java.png) **Java**](https://code.visualstudio.com/docs/languages/java)|[![Alt text](assets/images/js.png)**Javascript**](https://code.visualstudio.com/docs/languages/javascript)|
+
+The Language Features are also shared with those in VS Code:
+- Syntax highlighting and bracket matching
+- Smart completions
+- Linting and corrections
+- Code navigation
+- Debugging
+- Refactoring
diff --git a/ide-refactoring.md b/ide-refactoring.md
@@ -0,0 +1,70 @@
+---
+title: Refactoring
+layout: home
+nav_order: 5
+parent: Oniro IDE
+---
+
+[Code Refactoring](https://refactoring.guru/refactoring) is an essential part of the software engineering life cycle. In this topic we will explain a few refactoring actions that are embedded into the IDE namely, `Rename Symbol`, `Extract Method`, and `Extract Variable`.
+
+## Rename Symbol
+This is mainly a refactoring tool that allows you to rename a symbol (variable, function, method, class, etc.) throughout your codebase consistently. This is particularly useful when you want to rename a symbol without manually updating each occurrence in different files.
+
+![Alt text](assets/images/rename-symbol.png)
+
+Right click on a symbol you want to rename and choose `Rename Symbol` or press F2. Write the new name and press `Enter`, or press `Shift+Enter` to preview your changes in a separate pane before applying them.
+
+## Extract Method
+The "Extract Method" refactoring action in Oniro IDE allows you to take a block of code within a function and create a new method for that block. This can improve code readability, maintainability, and reusability. Here's an example in javascript to illustrate how to use the "Extract Method" feature:
+
+```
+function calculateTotal(price, quantity) {
+  let taxRate = 0.1;
+  let subtotal = price * quantity;
+  let tax = subtotal * taxRate;
+  let total = subtotal + tax;
+
+  console.log("Total: $" + total.toFixed(2));
+}
+```
+
+If you want to extract tax calculation part into a separate method you could use the `Extract Method`. Simply select the code fragment, click on the light bulb and choose the scope for the new function. During the extract refactoring, you will be prompted to provide a meaningful name. The final code should look like this:
+
+```
+function calculateTotal(price, quantity) {
+  let taxRate = 0.1;
+  let subtotal = price * quantity;
+  let tax = calcTax(subtotal);
+  let total = subtotal + tax;
+
+  console.log("Total: $" + total.toFixed(2));
+}
+
+function calcTax(subtotal) {
+  let taxRate = 0.1;
+  return subtotal * taxRate;
+}
+```
+
+## Extract Variable
+allows you to take an expression in your code and create a new variable to store the result of that expression. Let's revisit our initial example:
+```
+function calculateTotal(price, quantity) {
+  let taxRate = 0.1;
+  let subtotal = price * quantity;
+  let total = subtotal + subtotal * taxRate;
+
+  console.log("Total: $" + total.toFixed(2));
+}
+```
+This time the total is calculated right away in long formula that includes the tax calculation. To make it more readable we want to extract the tax calculation in a separate variable. Hence, we select the `subtotal * taxRate` code fragment, click on the light bulb, choose `Extract to constant in enclosing scope` and give the constant a name eg. tax. The outcome should be as follows:
+```
+function calculateTotal(price, quantity) {
+  let taxRate = 0.1;
+  let subtotal = price * quantity;
+  const tax = subtotal * taxRate;
+  let total = subtotal + tax;
+
+  console.log("Total: $" + total.toFixed(2));
+}
+```
diff --git a/user-interface.md → ide-user-interface.md b/user-interface.md → ide-user-interface.md
@@ -1,8 +1,8 @@
 ---
 title: User Interface
 layout: home
-nav_order: 1
-parent: Oniro IDE Documentation
+nav_order: 2
+parent: Oniro IDE
 ---
 # User Interface
 
@@ -22,8 +22,8 @@ The basic layout consists of 8 main areas:
 1. **Secondary Side Bar**: hosts an extra view on the right hand side such as a `Debugging` side bar.
 
 
-## Explorer
-The explorer is used to browse, open, and manage all the files and folders in your project. You can create a new file or folder at any time in your project. You can also switch to a different project previously opened in the IDE by selecting it from the active project menu.
+## Explorer 
+The explorer is used to browse, open, and manage all the files and folders in your project. You can create a new file or folder at any time in your project.
 
 You can do many things to files and folders in the explorer:
 

diff --git a/oniro-ide-docs.md b/oniro-ide-docs.md
diff --git a/oniro-ide.md b/oniro-ide.md
@@ -0,0 +1,21 @@
+---
+layout: home
+title: Oniro IDE
+nav_order: 4
+has_children: true
+---
+
+<!-- 1. Getting Started (ide-getting-started)
+2. User Interface (ide-user-interface)
+3. Code Editing (ide-code-editing)
+4. Code Navigation (ide-code-navigation) 
+5. Refactoring (ide-refactoring)
+6. Building and Debugging (ide-building-and-debugging)
+7. Language Support (ide-language-support)
+-->
+
+# Oniro IDE
+Oniro IDE is an [Eclipse Theia](https://theia-ide.org/) based IDE built on the Oniro Operating System. It allows developers to build applications on a wide range of smart devices in what is called "One-time development". One set of code can adapt to multiple ends improving development efficiency and implementing cross-end service ecosystem sharing.
+
+Here we give a quick guide to the different features of the IDE and what is expected to come in the future.
+