Merge pull request #288 from vinzbarbuto/main

Updated documentation for upcoming VSCode extension release

docs/glossary/glossary.mdx

@@ -0,0 +1,61 @@
+---
+title: Glossary
+description: Glossary of terms used in the Lingua Franca documentation.
+---
+
+# Glossary
+
+Glossary of terms used in the Lingua Franca (LF) documentation.
+
+### LF File
+A source file with the `.lf` extension, representing a Lingua Franca (LF) program.
+
+### Library File
+An LF file containing one or more reactors intended for reuse, designed to be imported into other LF files.
+
+### Package
+A collection of LF source files and directories, along with a `Lingo.toml` manifest file that defines the package configuration. Every package must include an `src/` directory containing the LF source files.
+
+### Package Manager
+A software tool that automates the installation, configuration, and management of packages. In the LF ecosystem, the `lingo` package manager is used to manage LF packages and dependencies.
+
+### Package Root
+The **package root** is the top-level directory of a package where both the `Lingo.toml` file and the `src/` directory reside.
+
+### Project
+Another term for a [package](#package) that is under development. Each [LF file](#lf-file) is assumed to reside in a package, meaning it is located somewhere in the file system in a directory called `src`, in some directory that serves as the (package root)[#package-root].
+
+### Project Structure
+The structure of an LF project should follow the directory layout below:
+
+```
+├── .
+│   ├── bin/                # Directory for storing binary executables
+│   ├── build/              # Directory containing packages installed by the Lingo Package Manager
+│   │   ├── lfc_include/    # Directory for storing reusable reactors
+│   │   └── <Installed Package>/ # Directory containing the installed package
+│   ├── include/            # Directory for storing header files
+│   ├── src/                # Directory containing LF source files
+│   │   ├── lib/            # Directory for storing reusable reactors
+│   │   │   ├── Input.lf    # Ex: reactor capturing external inputs (e.g., Microphone, Camera)
+│   │   │   └── ComputerVision.lf # Ex: reactor performing computer vision tasks (e.g., object detection, face recognition)
+│   │   └── Main.lf         # Ex: main source file
+│   ├── fed-gen/            # Directory for storing generated code for federated programs
+│   ├── src-gen/            # Directory for storing generated code for single-process programs
+└── └── Lingo.toml          # Configuration file for Lingo Package Manager
+```
+
+- **Mandatory Directories and Files:**
+  - `src/`: This folder must contain at least one `.lf` source file.
+  - `Lingo.toml`: This is the required configuration file.
+
+- **Automatically Generated Directories:**
+  - `bin/`: Created during the build process to store binary executables.
+  - `build/`: Generated automatically when installing packages managed by the Lingo Package Manager.
+  - `include/`: Autogenerated to store header files.
+  - `src-gen/` (or `fed-gen` for federated programs): Autogenerated to store generated code.
+
+- **User-Created Directory:**
+  - `src/lib/`: This folder is for library files and should be created by the user as necessary.
+
+This directory structure is essential for enabling the Package Explorer feature in the [VS Code Extension](tools/code-extension.mdx#package-explorer), streamlining project management and development processes.

docs/sidebars.ts

@@ -237,6 +237,10 @@ const sidebars: SidebarsConfig = {
           "id": "developer/website-development"
         }
       ]
+    },
+    {
+      "type": "doc",
+      "id": "glossary/glossary"
     }
   ]
 };

docs/tools/code-extension.mdx

@@ -3,22 +3,57 @@ title: VS Code Extension
 description: Visual Studio Code Extension for Lingua Franca.
 ---
 
-The Lingua Franca extension for Visual Studio Code (VS Code) provides syntax-directed editing capability, compilation, and diagram synthesis for Lingua Franca programs.
+import Image from '@theme/IdealImage';
+import lingo_packages from '../assets/images/vs_code/lingo_packages.png';
+import local_libraries from '../assets/images/vs_code/local_libraries.png';
+import error_message from '../assets/images/vs_code/error_message.png';
+
+The Lingua Franca extension for Visual Studio Code (VS Code) provides syntax-directed editing capability, compilation, diagram synthesis and a package explorer for Lingua Franca programs.
 
 ## Usage
 
-### Creating a new file
+### Creating a New Project
+
+You can create a new LF [project](../glossary/glossary.mdx#project) either manually by creating an LF file or by using the [Lingo Package Manager](https://github.com/lf-lang/lingo).
+
+#### Option 1: Create a Project Using the Lingo Package Manager
+1. After [installing the Lingo Package Manager](https://www.lf-lang.org/docs/installation#lingo), create an empty directory to serve as the root of your new package.
+2. Open the folder in VS Code.
+3. Open the terminal in this folder and run the <kbd>lingo init</kbd> command. 
+
+This will set up a new LF package with the following structure:
+
+```
+├── .
+│   ├── src/
+│   │  └── Main.lf
+└── └── Lingo.toml # Configuration file for current package
+```
 
-To create a new LF file, go to <kbd>File > New File...</kbd> and select `New Lingua Franca File`. When saving the file, save it in a directory called `src` to make sure that generated code is placed conveniently in an adjacent `src-gen` directory. For instance, for a file called `Foo.lf`, the directory structure after building should look something like this:
+#### Option 2: Create a New [LF File](../glossary/glossary.mdx#lf-file)
+1. Go to <kbd>File > New File...</kbd> and select `New Lingua Franca File`.
+2. Save the file in a directory called `src` to ensure that generated code is placed in a parallel `src-gen` directory. For example, if your file is called `Foo.lf`, the directory structure after building will look like this:
 
 ```
-bin/Foo
-src/
-└ Foo.lf
-src-gen/Foo
+├── .
+│   ├── bin/
+│   │  └── Foo
+│   ├── src/
+│   │  └── Foo.lf
+│   ├── src-gen/
+│   │  └── Foo/
+...
 ```
 
-### Rendering diagrams
+If you manually create the `Lingo.toml` file, place it adjacent to the `src` folder in the root directory of the package. This file serves as a configuration for the package, allowing you to specify the package name, version, and other metadata, including any dependencies you want to install.
+
+### Opening an Existing LF Project
+
+To open an existing LF project in VS Code, select the [package root](../glossary/glossary.mdx#package-root) as your workspace. Ensure that the selected project adheres to the correct [project structure](../glossary/glossary.mdx#project-structure) to enable the [Package Explorer](#package-explorer). If the workspace is not recognized as a valid Lingua Franca package, an error message will appear when you attempt to open the Package Explorer:
+
+<Image img={error_message} style={{maxWidth: 400}} />
+
+### Rendering Diagrams
 
 To show the diagram for the currently active Lingua Franca file, click on the diagrams icon at the upper right:
 
@@ -31,6 +66,136 @@ To compile the `.lf` source, open the command palette (<kbd>Ctrl</kbd> + <kbd>Sh
 You can also build and immediately afterwards run your code by opening the command palette (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) and then entering `Lingua Franca: Build and Run`.
 Running the code can also be done from the VS Code terminal by executing the generated file in `./bin`.
 
+### Package Explorer
+
+The **Lingua Franca Package Explorer** can be accessed by clicking on the **LF icon** in the activity bar on the left side of the screen. Once opened, the **Package Explorer** displays a **Tree View** with the following structure:
+
+```
+├── <Package Name>
+│   ├── Installed Packages
+│   ├── Local Libraries
+└── └── Source Files
+```
+
+- [**Installed Packages**](#installed-packages): Lists packages installed via the Lingo Package Manager, located in the `./build/lfc_include` directory (if any).
+
+- [**Local Libraries**](#local-libraries): Displays locally defined [library files](../glossary/glossary.mdx#library-file) (e.g., reusable reactors), located in the `./src/lib` directory.
+
+- [**Source Files**](#source-files): Contains the LF source files created by the developer, located in the `./src/` directory.
+
+The **Source Files** section is always present as it reflects the main LF files in the package. However, the **Installed Packages** and **Local Libraries** sections appear only if the respective directories and files exist in the workspace.
+
+Hovering over the **\<Package Name\>** item reveals a terminal icon. Clicking this icon opens a terminal window at the package's root directory, allowing you to execute commands directly within that directory.
+
+#### Installed Packages
+
+The **Installed Packages** section lists libraries installed using the [Lingo package manager](https://github.com/lf-lang/lingo). Developers can use the Lingo package manager to retrieve and install LF programs from arbitrary GitHub repositories. A collection of useful packages can be found in the [Lingua Franca Packages](https://github.com/lf-pkgs) GitHub organization.
+
+To install packages:
+1. Configure the `Lingo.toml` file with the desired package.
+2. Run <kbd>lingo build</kbd> in the terminal from the current directory to download the specified dependencies.
+
+Once the packages are installed, they will appear in the `./build/lfc_include/` directory. The **Installed Packages** section will then be structured as follows:
+
+```
+├── <Package Name>
+│   ├── Installed Packages
+│   │  ├── <Installed Package>
+│   │  │   ├── File_1.lf
+│   │  │   │   ├── Rusable_Reactor_1.lf
+│   │  │   │   ├── Rusable_Reactor_2.lf
+│   │  │   ├── File_2.lf
+│   │  │   │   ├── Rusable_Reactor_1.lf
+│   │  │   │   ├── Rusable_Reactor_2.lf
+...
+```
+
+In this structure:
+- **\<Package Name\>**: Represents the root folder of the main package.
+- **\<Installed Package\>**: Represents each package listed in `Lingo.toml`, which contains one or more LF projects featuring reusable reactors.
+
+The image below shows a visual representation of the **Installed Packages** section. The **project** icon indicates the LF Package folder (e.g., `AudioClassification`), while the **root-folder** icon represents the downloaded package (e.g., the `edgeai` package in the example). The **code file** icon denotes an LF program within a package, and the **bracket** icon represents individual reactors inside the LF program.
+
+<Image img={lingo_packages} style={{maxWidth: 400}} />
+
+The hierarchy categorizes tree items into the following types:
+
+1. **package root**: Refers to the root folder of each downloaded package.
+2. **file**: Represents an LF file within the package.
+3. **reactor**: Refers to individual reactors within the LF file.
+
+When focusing on the **Installed Packages** section, an `edit` command becomes available. Clicking it opens the `Lingo.toml` file in the editor for configuration changes. The following actions are available for items in the **Installed Packages** section:
+
+- For **file** items (from right to left):
+  - **Open in Split View**: Opens the file in a split editor view.
+  - **Go To File**: Navigates to the file in the editor.
+
+- For **reactor** items (from right to left):
+  - **Import Selected Reactor**: Imports the selected reactor into the active LF program.
+  - **Go To File**: Opens the file where the reactor is defined.
+  - **Open in Split View**: Opens the file in a split editor view (accessible by right-clicking the item).
+
+:::note
+The **Import Selected Reactor** option is available only if an LF program is open in the editor.
+:::
+
+#### Local Libraries
+
+The **Local Libraries** section lists LF programs created by the developer, located in the `./src/lib/` directory. These programs serve as local libraries, containing reusable reactors. The directory structure follows this format:
+
+```
+├── <Package Name>
+...
+│   ├── Local Libraries
+│   │  ├── File_1.lf
+│   │  │   ├── Rusable_Reactor_1.lf
+│   │  │   ├── Rusable_Reactor_2.lf
+│   │  ├── File_2.lf
+│   │  │   ├── Rusable_Reactor_1.lf
+│   │  │   ├── Rusable_Reactor_2.lf
+...
+```
+
+The image below illustrates the **Local Libraries** section. In this depiction, the **"project"** icon represents the LF package folder, while the **"code file"** icon represents the LF program, and the **"bracket"** icon denotes individual reactors within the LF program.
+
+<Image img={local_libraries} style={{maxWidth: 400}} />
+
+The hierarchy categorizes tree items into two types:
+
+1. **file**: Represents the LF file.
+2. **reactor**: Represents a reactor within the LF file.
+
+Actions for **Local Libraries** are similar to those in the [**Installed Packages**](#installed-packages) section:
+
+- For **file** items (from right to left):
+  - **Open in Split View**: Opens the file in a split editor view.
+  - **Go To File**: Navigates to the file in the editor.
+
+- For **reactor** items (from right to left):
+  - **Import Selected Reactor**: Imports the selected reactor into the active LF program.
+  - **Go To File**: Opens the file where the reactor is defined.
+  - **Open in Split View**: Opens the file in a split editor view (accessible by right-clicking the item).
+
+:::note
+The **Import Selected Reactor** option is available only if an LF program is open in the editor.
+:::
+
+#### Source Files
+
+The **Source Files** section lists all LF programs in the `./src/` directory. This section provides direct access to the main source files of the package. The hierarchy for this view is straightforward:
+
+```
+├── <Package Name>
+...
+│   ├── Source Files
+│   │  ├── File_1.lf
+│   │  ├── File_2.lf
+│   │  ├── File_3.lf
+...
+```
+
+Clicking on any of the files will open the corresponding LF program in the editor, providing a way to quickly navigate and edit the source code of a package.
+
 ## Notes
 
 ### For Python Users