Debian Codegraph @

doc/contributing/environment.md

raw
1 Setting up Development Environment
2 ==================================
3
4 Getting started with DataLab development is easy.
5
6 Here is what you will need:
7
8 1. An integrated development environment (IDE) for Python. We recommend
9 [Spyder](https://www.spyder-ide.org/) or [Visual Studio Code](https://code.visualstudio.com/),
10 but any IDE will do.
11
12 2. A Python distribution. We recommend [WinPython](https://winpython.github.io/),
13 on Windows, or [Anaconda](https://www.anaconda.com/), on Linux or Mac.
14 But, again, any Python distribution will do.
15
16 3. A clean project structure (see below).
17
18 4. Test data (see below).
19
20 5. Environment variables (see below).
21
22 6. Third-party software (see below).
23
24 Development Environment
25 -----------------------
26
27 If you are using [Spyder](https://www.spyder-ide.org/), thank you for supporting
28 the scientific open-source Python community!
29
30 If you are using Visual Studio Code, that's also an excellent choice (for other
31 reasons). We recommend installing the following extensions:
32
33 | Extension | Description |
34 | --------- | ----------- |
35 | [gettext](https://marketplace.visualstudio.com/items?itemName=mrorz.language-gettext) | Gettext syntax highlighting |
36 | [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) | Python language server |
37 | [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) | Python extension |
38 | [reStructuredText Syntax highlighting](https://marketplace.visualstudio.com/items?itemName=trond-snekvik.simple-rst) | reStructuredText syntax highlighting |
39 | [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) | Extremely fast Python linter and code formatter |
40 | [Todo Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree) | Todo tree |
41 | [Insert GUID](https://marketplace.visualstudio.com/items?itemName=heaths.vscode-guid) | Insert GUID |
42 | [XML Tools](https://marketplace.visualstudio.com/items?itemName=DotJoshJohnson.xml) | XML Tools |
43
44 Python Environment
45 ------------------
46
47 DataLab requires the following :
48
49 * Python (e.g. WinPython)
50
51 * Additional Python packages
52
53 Installing all required packages :
54
55 pip install --upgrade -r requirements.txt
56
57 ℹ️ See [Installation](https://datalab-platform.com/en/intro/installation.html)
58 for more details on reference Python and Qt versions.
59
60 ⚠️ If you are contributing to DataLab's processing features, you will need to work on both DataLab's main repository and sigima's repository. To install `sigima` in editable mode, use the following command:
61
62 pip install -e ../sigima # Adjust the path to your local sigima repository
63
64 If you are using [WinPython](https://winpython.github.io/), thank you for supporting
65 the scientific open-source Python community!
66
67 The following table lists the currently officially used Python distributions:
68
69 | Python version | Status | WinPython version |
70 | -------------- | ------------ | ----------------- |
71 | 3.9 | OK | 3.9.10.0 |
72 | 3.10 | OK | 3.10.11.1 |
73 | 3.11 | OK | 3.11.5.0 |
74 | 3.12 | OK | 3.12.3.0 |
75 | 3.13 | OK | 3.13.2.0 |
76
77 ⚠ We strongly recommend using the `.dot` versions of WinPython which are lightweight
78 and can be customized to your needs (using `pip install -r requirements.txt`).
79
80 ✅ We also recommend using a dedicated WinPython instance for DataLab.
81
82 Test data
83 ---------
84
85 DataLab test data are located in different folders, depending on their nature or origin.
86
87 Required data for unit tests are located in "datalab\data\tests" (public data).
88
89 A second folder %DATALAB_DATA% (optional) may be defined for additional tests which are
90 still under development (or for confidential data).
91
92 Specific environment variables
93 ------------------------------
94
95 Enable the "debug" mode (no stdin/stdout redirection towards internal console):
96
97 @REM Mode DEBUG
98 set DEBUG=1
99
100 Building PDF documentation requires LaTeX. On Windows, the following environment:
101
102 @REM LaTeX executable must be in Windows PATH, for mathematical equations rendering
103 @REM Example with MiKTeX :
104 set PATH=C:\\Apps\\miktex-portable\\texmfs\\install\\miktex\\bin\\x64;%PATH%
105
106 Visual Studio Code configuration used in `launch.json` and/or `tasks.json`
107 (examples) :
108
109 @REM Folder containing additional working test data
110 set DATALAB_DATA=C:\Dev\Projets\DATALAB_data
111
112 Visual Studio Code `.env` file:
113
114 * This file is used to set environment variables for the application.
115 * It is used to set the `PYTHONPATH` environment variable to the root of the project.
116 * This is required to be able to import the project modules from within VS Code.
117 * To create this file, copy the `.env.template` file to `.env`
118 (and eventually add your own paths).
119
120 Windows installer
121 -----------------
122
123 The Windows installer is built using [WiX Toolset](https://wixtoolset.org/) V4.0.5.
124 Using the WiX Toolset requires [.NET SDK](https://dotnet.microsoft.com/download/dotnet/) V6.0 minimum.
125
126 You may install .NET SDK using `winget`:
127
128 winget install Microsoft.DotNet.SDK.8
129
130 Once .NET SDK is installed, the WiX Toolset can be installed and configured using the
131 following commands:
132
133 dotnet tool install --global wix --version 4.0.5
134 wix extension add WixToolset.UI.wixext/4.0.5
135
136 First, you need to generate the installer script from a generic template:
137
138 python wix/makewxs.py
139
140 Building the installer is done using the following command:
141
142 wix build .\wix\DataLab.wxs -ext WixToolset.UI.wixext
143
144 Third-party Software
145 --------------------
146
147 The following software may be required for maintaining the project:
148
149 | Software | Description |
150 | -------- | ----------- |
151 | [gettext](https://mlocati.github.io/articles/gettext-iconv-windows.html) | Translations |
152 | [Git](https://git-scm.com/) | Version control system |
153 | [ImageMagick](https://imagemagick.org/) | Image manipulation utilities |
154 | [Inkscape](https://inkscape.org/) | Vector graphics editor |
155 | [MikTeX](https://miktex.org/) | LaTeX distribution on Windows |