Skip to content

Commit c9954ad

Browse files
d-biehld-biehl
committed
docs: "Get Started" improved
1 parent da0af7b commit c9954ad

File tree

5 files changed

+257
-102
lines changed

5 files changed

+257
-102
lines changed

‎docs/.vitepress/config.mts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
import { defineConfig } from "vitepress";
22
import { generateSidebar } from "vitepress-sidebar";
33
import taskLists from "markdown-it-task-lists";
4+
import kbd from "markdown-it-kbd";
5+
import abbr from "markdown-it-abbr";
46
import { tabsMarkdownPlugin } from "vitepress-plugin-tabs";
57
import robotframework from "../../syntaxes/robotframework.tmLanguage.json";
68
import { readFileSync } from "fs";
@@ -95,6 +97,8 @@ export default defineConfig({
9597
},
9698
markdown: {
9799
config(md: any) {
100+
md.use(kbd);
101+
md.use(abbr);
98102
md.use(taskLists);
99103
md.use(tabsMarkdownPlugin);
100104
},

‎docs/.vitepress/theme/style.css

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,4 +166,15 @@ img[src*="shields.io"] {
166166
height: 26px;
167167
vertical-align: middle;
168168
display: inline;
169+
}
170+
171+
kbd {
172+
display: inline-block;
173+
padding: 0px 6px;
174+
font-family: var(--vp-font-family-mono);
175+
color: var(--color-fg-default);
176+
vertical-align: middle;
177+
background-color: var(--vp-input-switch-bg-color);
178+
border: 1px solid var(--vp-input-border-color);
179+
border-radius: 6px;
169180
}

‎docs/02_get_started/index.md

Lines changed: 146 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,191 @@
1-
# Get Started
1+
# Let's get started!!!
2+
3+
Let's explore how you can enhance your development experience with RobotCode - Robot Framework for Visual Studio Code. We'll walk you through the steps of installing the RobotCode extension, configuring your environment, and ensuring smooth functionality. Get ready to unleash the power of RobotCode and Robot Framework in no time!
24

3-
Welcome to RobotCode! In this section, we will get your Visual Studio Code set up and go through the basics: installing the extension, setting up your environment, and verifying everything is working smoothly.
45

56
## Requirements
7+
68
- Python 3.8 or above
79
- Robotframework version 4.1 and above
810
- VSCode version 1.86 and above
911

1012
## Installing RobotCode
1113

14+
To install RobotCode and set up your Robot Framework project in Visual Studio Code, follow these steps:
15+
1216
1. Open Visual Studio Code.
13-
2. Inside Visual Studio Code, create a new project folder or open an existing one where you want to set up your Robot Framework project.
14-
3. Go to the **Extensions** tab (Shortcut key <kbd>CONTROL</kbd>+<kbd>SHIFT</kbd>+<kbd>X</kbd>).
15-
4. Search for **RobotCode** and install the extension ![RobotCode Icon](/robotcode-logo.svg "RobotCode Icon"){.inline-icon} [RobotCode - Robot Framework Support](https://marketplace.visualstudio.com/items?itemName=d-biehl.robotcode "RobotCode Extension"). This will also install the **Python** and **Python Debugger** extensions.
16-
5. **(Recommended)** Install the **Even Better TOML** extension for handling `.toml` files more effectively. This will be helpful when setting up your project settings in the [Configuration](./configuration) section.
17+
2. Go to the **Extensions** tab by pressing [[CONTROL+SHIFT+X]] or [[COMMAND+SHIFT+X]] on Mac
18+
3. Search for **RobotCode** and install the [RobotCode - Robot Framework Support](https://marketplace.visualstudio.com/items?itemName=d-biehl.robotcode) extension. This will also install the **Python** and **Python Debugger** extensions.
19+
4. *(Recommended)* Install the **Even Better TOML** extension for better handling of `.toml` files, which will be useful when configuring your project settings in the [Configuration](./configuration) section.
20+
21+
22+
::: details Tip: Add to Workspace Recommendations (Optional)
23+
24+
To ensure a consistent development environment for everyone working on this project, follow these steps:
25+
26+
1. Right-click on the RobotCode extension in the Extensions tab.
27+
2. Click on **Add to Workspace Recommendations**. This will prompt all team members to install the RobotCode extension, creating a unified development environment.
28+
29+
![RobotCode](images/robotcode-add-to-workspace.gif)
30+
31+
:::
32+
33+
See also the VSCode Documention on how to work with extensions [here](https://code.visualstudio.com/docs/editor/extension-marketplace).
34+
35+
36+
## Setup a Robot Framework Project
37+
38+
First you need to open your project folder in Visual Studio Code. You can do this by selecting **File > Open Folder** menu and navigating to the root folder of your project. If you don't have a project folder yet, you can also create a new folder in the "Open Folder" dialog.
39+
40+
It is a good style to manage your project dependencies in a `requirements.txt` file. This file lists all the Python packages required for your project, including Robot Framework and any other dependencies you may need. This file can be used to install all the dependencies at once, ensuring that your project runs consistently across different environments.
1741

18-
After installation:
19-
- Right-click on the RobotCode extension in the Extensions tab.
20-
- Click **Add to Workspace Recommendations** to ensure that all team members working on this project are prompted to install the RobotCode extension, creating a consistent development environment for everyone.
42+
::: tip Note
43+
However, it's important to note that there are alternative and better methods for setting up a Robot Framework project. Tools like [Hatch](https://hatch.pypa.io/) or [Poetry](https://python-poetry.org/) offer additional features and flexibility for managing project dependencies and environments.
44+
:::
2145

22-
![RobotCode](images/robotcode-add-to-workspace.gif){style="width: 30%;"}
46+
Create a `requirements.txt` file in the root folder of your project and add the following content:
2347

24-
## Initialize an Empty Project
48+
```requirements.txt [requirements.txt]
49+
robotframework
50+
```
2551

26-
To get started with your Robot Framework project, we'll create a `requirements.txt` file to list all necessary dependencies, and set up a virtual Python environment to ensure these dependencies are installed in an isolated space, avoiding conflicts with other projects.
52+
If you require additional dependencies, you can include them in the `requirements.txt` file. For instance, if you wish to utilize [robotframework-tidy](https://github.com/MarketSquare/robotframework-tidy) for formatting your robot files and the [Browser library](https://robotframework-browser.org/) for website testing, you can add the following line to the `requirements.txt` file:
2753

28-
1. **Create a `requirements.txt` file** in the root folder of your project and add the following dependencies:
29-
::: code-group
30-
```txt:line-numbers [requirements.txt]
54+
```requirements.txt [requirements.txt]
3155
robotframework
3256
robotframework-tidy
57+
robotframework-browser
3358
```
59+
60+
### Installing Dependencies
61+
62+
::: warning
63+
Depending on your requirements and system environment, it is advisable to avoid using the system python interpreter for development. Utilizing the system python interpreter can potentially cause conflicts with other projects or system dependencies. Instead, it is recommended to create a virtual environment for your project. Please refer to the [Creating a Virtual Python Environment](#creating-a-virtual-python-environment) section for detailed instructions.
64+
65+
However, there are scenarios where using the system python interpreter is acceptable, such as when working with a docker container or a CI/CD pipeline. In such cases, you can skip the virtual environment setup and directly install the dependencies to the system python interpreter.
66+
67+
If you want to use a virtual environment, please continue with the [Creating a Virtual Python Environment](#creating-a-virtual-python-environment) section.
68+
:::
69+
70+
To install the dependencies listed in the `requirements.txt` file, open the terminal in Visual Studio Code and run the following command:
71+
72+
```shell
73+
pip install -r requirements.txt
74+
```
75+
76+
This command will install the Robot Framework and any other dependencies listed in the `requirements.txt` file. Make sure to run this command in the root folder of your project.
77+
78+
79+
#### Creating a Virtual Python Environment
80+
81+
It is recommended to use a virtual python environment for your project to manage dependencies and ensure consistency across different environments. A virtual environment allows you to isolate your project's dependencies from the system-wide Python installation, ensuring that your project runs consistently across different environments.
82+
83+
::: details What is a Virtual Python Environment?
84+
85+
A virtual environment is a self-contained directory that contains a Python installation along with all the necessary packages and dependencies for a specific project.
86+
87+
Using a virtual environment is beneficial for several reasons:
88+
- Dependency management: By creating a virtual environment, you can easily manage and install project-specific dependencies without affecting other Python projects or the system-wide Python installation.
89+
- Version control: Including the virtual environment directory in your project's version control system ensures that all developers working on the project have the same environment setup, avoiding compatibility issues.
90+
- Reproducibility: With a virtual environment, you can recreate the exact environment in which your project was developed, making it easier to reproduce and debug issues.
91+
92+
More informations about virtual environments can be found in the [Python documentation](https://docs.python.org/3/library/venv.html).
93+
3494
:::
3595

36-
2. **Set up your Python environment:**
96+
There are several ways to create a virtual Python environment and managing you project and project dependencies, depending on your preference and workflow. Below, we use the standard builtin python methods and describe two ways for creating a virtual environment: the "VSCode way" and the "Python way".
97+
Some other good options to manage your Robot Framework/Python environment are [hatch](https://hatch.pypa.io/), [poetry](https://python-poetry.org/) or [pipenv](https://pipenv.pypa.io/en/latest/)
98+
99+
:::tabs
100+
=== The VSCode way
101+
102+
VSCode provides a built-in feature to create a virtual environment for your Robot Framework/ Python project. This feature allows you to create a virtual environment and install dependencies directly from the editor. You can also specify the Python version and include one or more `requirements.txt` files for managing project dependencies.
103+
104+
You can refer to the [Python environments in VSCode Documentation](https://code.visualstudio.com/docs/python/environments) for more information.
37105

38-
A virtual environment is a self-contained directory that contains a Python installation for a particular version of Python, plus a number of additional packages. This helps keep your project dependencies isolated from other projects. In this step we will let Visual Studio Code create a virtual environment using the selected Python version, install the dependencies listed in requirements.txt, and activate the virtual environment. This ensures that your project has all the necessary packages and an isolated environment for development.
106+
The short version of the steps are:
39107

40-
1. Click on **Create Environment** in Visual Studio Code. If this button isn't visible,
41-
you can alternatively open the Command Palette by pressing
42-
<kbd>CONTROL</kbd>+<kbd>SHIFT</kbd>+<kbd>P</kbd>, then search for **Python: Create Environment**, and select it.
43-
2. Choose **venv**, which stands for Virtual Environment.
108+
1. Open the Command Palette by pressing
109+
[[CONTROL+SHIFT+P]] or [[COMMAND+SHIFT+P]] on Mac, then search for `Python: Create Environment`, and select it.
110+
2. Choose `Venv`, this will create a virtual environment in the `.venv` folder in your project.
44111
3. Select your preferred Python version.
45112
4. Check the box for requirements.txt and click OK.
46113

47114
![Create python environment](images/python-create-env.gif)
48115

116+
=== The Python way
117+
118+
To create a virtual environment in Python, you can use the built-in `venv` module. This module provides a command-line interface as well as a Python API for managing virtual environments.
119+
120+
Open a Terminal in VSCode and ensure you are in the root folder of your project. Then follow these steps:
121+
122+
1. Create a virtual environment:
123+
```
124+
python -m venv .venv
125+
```
126+
127+
2. Activate the virtual environment:
128+
::: code-group
129+
``` shell [Windows PowerShell/pwsh]
130+
myenv\Scripts\activate.ps1
131+
```
132+
133+
``` shell [Windows CMD]
134+
myenv\Scripts\activate.cmd
135+
```
136+
137+
``` shell [Mac/Linux]
138+
source myenv/bin/activate
139+
```
140+
:::
141+
142+
3. Install project-specific dependencies:
143+
```
144+
pip install -r requirements.txt
145+
```
146+
:::
147+
148+
149+
::: tip
150+
Remember to include the virtual environment directory `.venv` in your project's `.gitignore` file to avoid committing unnecessary files to your version control system.
151+
"""
152+
:::
153+
154+
## Selecting the Python Interpreter
155+
156+
After creating a virtual environment or if you want to switch to a different Python interpreter with Robot Framework installed for your project, you can select the Python interpreter in Visual Studio Code. This ensures that the correct Python environment is used for running your Robot Framework tests.
157+
158+
To select the Python interpreter, follow these steps:
159+
160+
1. Open the Command Palette by pressing [[CONTROL+SHIFT+P]] or [[COMMAND+SHIFT+P]] on Mac.
161+
2. Search for `Python: Select Interpreter` and select it.
162+
3. Choose the Python interpreter associated with your virtual environment or the Python interpreter with Robot Framework installed.
163+
164+
49165
## Verifying the Installation
50-
1. Open the terminal in Visual Studio Code. Make sure you are in the root folder of your project.
166+
167+
1. Open the terminal in Visual Studio Code. You can do this by pressing [[CONTROL+`]] or selecting **Terminal > New Terminal** from the menu. If there is an existing terminal, you can close it and open a new one to ensure that the virtual environment is activated.
51168
2. Run the command `robot --version` to check if Robot Framework is installed correctly.
52169
53-
If the command returns the Robot Framework version number, your installation is successful! If you encounter any errors, ensure that your virtual environment is activated and that all dependencies in `requirements.txt` have been installed.
170+
If the command returns the Robot Framework version number, your installation is successful!
171+
If you encounter any errors, ensure that your virtual environment is activated and that all dependencies in `requirements.txt` have been installed.
54172
55173
## Create and Run Your First Suite/Test
174+
56175
Create a `first.robot` file in your project with the following code to demonstrate a basic example of logging a string message to the debug console:
57176
58-
::: code-group
59-
```robot:line-numbers [first.robot]
177+
178+
```robot [first.robot]
60179
*** Test Cases ***
61180
First Test Case
62181
Log Hello world
63182
64183
```
65-
:::
184+
66185

67186
To run this test file, press the green play button next to the `First Test Case` keyword in the code.
68187
You should see the `Hello world` output displayed in the **Debug Console** of Visual Studio Code.
69188

70-
![RobotCode](images/robotcode-first-test-case.gif){style="width: 70%;"}
189+
![RobotCode](images/robotcode-first-test-case.gif)
71190

72191
And that's it! If you have any questions or run into issues, check out the RobotCode documentation or join our community in slack for support. Happy coding!

‎docs/package.json

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
"preview": "vitepress preview"
99
},
1010
"devDependencies": {
11+
"markdown-it-abbr": "^2.0.0",
12+
"markdown-it-kbd": "^2.2.2",
1113
"markdown-it-mathjax3": "^4.3.2",
1214
"markdown-it-task-lists": "^2.1.1",
1315
"typescript": "^5.5.4",

0 commit comments

Comments
 (0)