Skip to content

Commit 3617a5b

Browse files
markotoplakmarkotoplak
authored
Merge pull request #5278 from janezd/update-installation-instructions
README.md: Update installation instructions
2 parents f72c884 + 31394c0 commit 3617a5b

File tree

1 file changed

+137
-77
lines changed

1 file changed

+137
-77
lines changed

‎README.md‎

Lines changed: 137 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,17 @@
55
</p>
66
<p align="center">
77
<a href="https://orange.biolab.si/download" alt="Latest release">
8-
<img src="https://img.shields.io/github/v/release/biolab/orange3?label=download" /></a>
8+
<img src="https://img.shields.io/github/v/release/biolab/orange3?label=download" />
9+
</a>
910
<a href="https://orange3.readthedocs.io/en/latest/?badge=latest" alt="Documentation">
10-
<img src="https://readthedocs.org/projects/orange3/badge/?version=latest"></a>
11+
<img src="https://readthedocs.org/projects/orange3/badge/?version=latest">
12+
</a>
13+
<a href="https://discord.gg/FWrfeXV" alt="Discord">
14+
<img src="https://img.shields.io/discord/633376992607076354?logo=discord&color=7389D8&logoColor=white&label=Discord"> </a>
1115
</p>
1216

13-
# Orange
14-
[Orange] is a data mining and visualization toolbox for novice and expert alike. To explore data with Orange, one requires __no__ programming or in-depth mathematical knowledge. We believe that workflow-based data science tools democratize data science by hiding complex underlying mechanics and exposing intuitive concepts. Anyone who owns data, or is motivated to peek into data, should have the means to do so.
17+
# Orange Data Mining
18+
[Orange] is a data mining and visualization toolbox for novice and expert alike. To explore data with Orange, one requires __no programming or in-depth mathematical knowledge__. We believe that workflow-based data science tools democratize data science by hiding complex underlying mechanics and exposing intuitive concepts. Anyone who owns data, or is motivated to peek into data, should have the means to do so.
1519

1620
<p align="center">
1721
<a href="https://orange.biolab.si/download">
@@ -21,124 +25,180 @@
2125

2226
[Orange]: https://orange.biolab.si/
2327

24-
## Contributing
2528

26-
[![GitHub Actions](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fbiolab%2Forange3%2Fbadge&label=build)](https://actions-badge.atrox.dev/biolab/orange3/goto)
27-
[![codecov](https://img.shields.io/codecov/c/github/biolab/orange3)](https://codecov.io/gh/biolab/orange3)
28-
[![Contributor count](https://img.shields.io/github/contributors-anon/biolab/orange3)](https://github.com/biolab/orange3/graphs/contributors)
29-
[![Latest GitHub commit](https://img.shields.io/github/last-commit/biolab/orange3)](https://github.com/biolab/orange3/commits/master)
29+
## Installing
3030

31-
Want to get involved? Join us on [![Discord](https://img.shields.io/discord/633376992607076354?logo=discord&color=7389D8&logoColor=white&label=Discord)](https://discord.gg/FWrfeXV), introduce yourself in #general!
31+
### Easy installation
3232

33-
Take a look at our [contributing guide](https://github.com/irgolic/orange3/blob/README-shields/CONTRIBUTING.md), it might answer some questions, and it outlines the standards we adhere to.
33+
For easy installation, [![Download](https://img.shields.io/github/v/release/biolab/orange3?label=download)](https://orange.biolab.si/download) the latest released Orange version from our website. To install an add-on, head to `Options -> Add-ons...` in the menu bar.
3434

35-
Check out our widget development [![docs](https://readthedocs.org/projects/orange-widget-base/badge/?version=latest)](https://orange-widget-base.readthedocs.io/en/latest/?badge=latest) for a comprehensive guide on writing Orange widgets.
35+
### Installing with Conda
3636

37-
If you're looking for a good starting point, check out our [![good first issues](https://img.shields.io/github/issues/biolab/orange3/good%20first%20issue?label=good%20first%20issues)](https://github.com/biolab/orange3/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
37+
First, install [Miniconda](https://docs.conda.io/en/latest/miniconda.html) for your OS.
3838

39+
Then, create a new conda environment, and install orange3:
3940

40-
### The Orange Ecosystem
41+
```Shell
42+
# Add conda-forge to your channels for access to the latest release
43+
conda config --add channels conda-forge
4144

42-
The development of Orange is primarily split into three repositories:
45+
# Create and activate an environment for Orange
46+
conda create python=3 --yes --name orange3
47+
conda activate orange3
4348

44-
[biolab/orange-canvas-core](https://www.github.com/biolab/orange-canvas-core) implements canvas elements,
45-
[biolab/orange-widget-base](https://www.github.com/biolab/orange-widget-base) implements a widget window's interface elements,
46-
[biolab/orange3](https://www.github.com/biolab/orange3) brings it all together and implements the base data mining toolbox.
49+
# Install Orange
50+
conda install orange3
51+
```
4752

48-
Additionally, add-ons implement additional widgets for more specific use cases. [Anyone can write an add-on.](https://github.com/biolab/orange3-example-addon) Below is a list of our first-party add-ons:
53+
For installation of an add-on, use:
54+
```Shell
55+
conda install orange3-<addon name>
56+
```
57+
[See specific add-on repositories for details.](https://github.com/biolab/)
4958

50-
[biolab/orange3-text](https://www.github.com/biolab/orange3-text)
51-
[biolab/orange3-bioinformatics](https://www.github.com/biolab/orange3-bioinformatics)
52-
[biolab/orange3-timeseries](https://www.github.com/biolab/orange3-timeseries)
53-
[biolab/orange3-single-cell](https://www.github.com/biolab/orange3-single-cell)
54-
[biolab/orange3-imageanalytics](https://www.github.com/biolab/orange3-imageanalytics)
55-
[biolab/orange3-educational](https://www.github.com/biolab/orange3-educational)
56-
[biolab/orange3-geo](https://www.github.com/biolab/orange3-geo)
57-
[biolab/orange3-associate](https://www.github.com/biolab/orange3-associate)
58-
[biolab/orange3-network](https://www.github.com/biolab/orange3-network)
59+
#### Running
5960

60-
### Setting up
61+
Activate the environment,
62+
```Shell
63+
conda activate orange3
64+
```
65+
and run either `orange-canvas` or `python3 -m Orange.canvas`.
6166

62-
1. Set up a __virtual environment__. We recommend [Miniconda](https://docs.conda.io/en/latest/miniconda.html).
63-
`conda create python=3 --name orange3`
64-
2. __Fork__ your chosen repository.
65-
Press the fork button in top-right corner of the page
66-
3. __Clone__ it.
67-
`git clone ssh://git@github.com/<your-username>/<repo-name>`
68-
4. __Install__ it.
69-
`pip install -e .` or `python setup.py develop`
67+
Add `--help` for a list of program options.
7068

71-
Now you're ready to work with git. See GitHub's guides on [pull requests](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests), [forks](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/working-with-forks) if you're unfamiliar.
72-
If you're having trouble, get in touch on [![Discord](https://img.shields.io/discord/633376992607076354?logo=discord&color=7389D8&logoColor=white&label=Discord)](https://discord.gg/FWrfeXV).
69+
Starting up for the first time may take a while.
7370

74-
## Installing
71+
### Installing with pip
7572

76-
For easy installation, [![Download](https://img.shields.io/github/v/release/biolab/orange3?label=download)](https://orange.biolab.si/download) the latest released Orange version from our website.
73+
To install Orange with pip, run the following.
7774

78-
### Installing with Miniconda / Anaconda
75+
```Shell
76+
# Install build requirements via your system's package manager
77+
sudo apt install virtualenv build-essential python3-dev
7978

80-
Orange requires Python 3.6 or newer.
79+
# Create an environment for Orange and its dependencies
80+
virtualenv --python=python3 --system-site-packages orange3venv
8181

82-
First, install [Miniconda] for your OS. Create virtual environment for Orange:
82+
# Activate the environment
83+
source orange3venv/bin/activate
8384

84-
```Shell
85-
conda create python=3 --name orange3
85+
# Install Orange
86+
pip install orange3
8687
```
87-
In your Anaconda Prompt add conda-forge to your channels:
88+
89+
#### Running
90+
91+
Activate the environment by `source orange3venv/bin/activate`. Then run `orange-canvas` or `python3 -m Orange.canvas`. Add `--help` for a list of program options.
92+
93+
Starting up for the first time may take a while.
94+
95+
### Installing with winget (Windows only)
96+
97+
To install Orange with [winget](https://docs.microsoft.com/en-us/windows/package-manager/winget/), run:
8898

8999
```Shell
90-
conda config --add channels conda-forge
100+
winget install --id UniversityofLjubljana.Orange
91101
```
92102

93-
This will enable access to the latest Orange release. Then install Orange3:
103+
## Developing
104+
105+
[![GitHub Actions](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fbiolab%2Forange3%2Fbadge&label=build)](https://actions-badge.atrox.dev/biolab/orange3/goto) [![codecov](https://img.shields.io/codecov/c/github/biolab/orange3)](https://codecov.io/gh/biolab/orange3) [![Contributor count](https://img.shields.io/github/contributors-anon/biolab/orange3)](https://github.com/biolab/orange3/graphs/contributors) [![Latest GitHub commit](https://img.shields.io/github/last-commit/biolab/orange3)](https://github.com/biolab/orange3/commits/master)
106+
107+
Want to write a widget? [Use the Orange3 example add-on template.](https://github.com/biolab/orange3-example-addon)
108+
109+
Want to get involved? Join us on [![Discord](https://img.shields.io/discord/633376992607076354?logo=discord&color=7389D8&logoColor=white&label=Discord)](https://discord.gg/FWrfeXV), introduce yourself in #general!
110+
111+
Take a look at our [contributing guide](https://github.com/irgolic/orange3/blob/README-shields/CONTRIBUTING.md) and [style guidelines](https://github.com/biolab/orange-widget-base/wiki/Widget-UI).
112+
113+
Check out our widget development [![docs](https://readthedocs.org/projects/orange-widget-base/badge/?version=latest)](https://orange-widget-base.readthedocs.io/en/latest/?badge=latest) for a comprehensive guide on writing Orange widgets.
114+
115+
### The Orange ecosystem
116+
117+
The development of core Orange is primarily split into three repositories:
118+
119+
[biolab/orange-canvas-core](https://www.github.com/biolab/orange-canvas-core) implements the canvas,
120+
[biolab/orange-widget-base](https://www.github.com/biolab/orange-widget-base) is a handy widget GUI library,
121+
[biolab/orange3](https://www.github.com/biolab/orange3) brings it all together and implements the base data mining toolbox.
122+
123+
Additionally, add-ons implement additional widgets for more specific use cases. [Anyone can write an add-on.](https://github.com/biolab/orange3-example-addon) Some of our first-party add-ons:
124+
125+
- [biolab/orange3-text](https://www.github.com/biolab/orange3-text)
126+
- [biolab/orange3-bioinformatics](https://www.github.com/biolab/orange3-bioinformatics)
127+
- [biolab/orange3-timeseries](https://www.github.com/biolab/orange3-timeseries)
128+
- [biolab/orange3-single-cell](https://www.github.com/biolab/orange3-single-cell)
129+
- [biolab/orange3-imageanalytics](https://www.github.com/biolab/orange3-imageanalytics)
130+
- [biolab/orange3-educational](https://www.github.com/biolab/orange3-educational)
131+
- [biolab/orange3-geo](https://www.github.com/biolab/orange3-geo)
132+
- [biolab/orange3-associate](https://www.github.com/biolab/orange3-associate)
133+
- [biolab/orange3-network](https://www.github.com/biolab/orange3-network)
134+
- [biolab/orange3-explain](https://www.github.com/biolab/orange3-explain)
135+
136+
### Setting up for core Orange development
137+
138+
First, fork the repository by pressing the fork button in the top-right corner of this page.
139+
140+
Set your GitHub username,
94141

95142
```Shell
96-
conda install orange3
143+
export MY_GITHUB_USERNAME=replaceme
97144
```
98145

99-
[Miniconda]: https://docs.conda.io/en/latest/miniconda.html
100-
101-
To install the add-ons, follow a similar recipe:
146+
create a conda environment, clone your fork, and install it:
102147

103148
```Shell
104-
conda install orange3-<addon name>
149+
conda create python=3 --yes --name orange3
150+
conda activate orange3
151+
152+
git clone ssh://git@github.com/$MY_GITHUB_USERNAME/orange3
153+
154+
pip install -e orange3
105155
```
106156

107-
See specific add-on repositories for details.
157+
Now you're ready to work with git. See GitHub's guides on [pull requests](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests), [forks](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/working-with-forks) if you're unfamiliar. If you're having trouble, get in touch on [![Discord](https://img.shields.io/discord/633376992607076354?logo=discord&color=7389D8&logoColor=white&label=Discord)](https://discord.gg/FWrfeXV).
108158

109-
### Installing with pip
159+
#### Running
110160

111-
To install Orange with pip, run the following.
161+
Run Orange with `python -m Orange.canvas` (after activating the conda environment).
112162

113-
```Shell
114-
# Install some build requirements via your system's package manager
115-
sudo apt install virtualenv build-essential python3-dev
163+
`python -m Orange.canvas -l 2 --no-splash --no-welcome` will skip the splash screen and welcome window, and output more debug info. Use `-l 4` for more.
116164

117-
# Create a separate Python environment for Orange and its dependencies ...
118-
virtualenv --python=python3 --system-site-packages orange3venv
119-
# ... and make it the active one
120-
source orange3venv/bin/activate
165+
Add `--clear-widget-settings` to clear the widget settings before start.
121166

122-
# Install Orange
123-
pip install orange3
124-
```
167+
To explore the dark side of the Orange, try `--style=fusion:breeze-dark`
125168

126-
### Installing with winget (Windows only)
169+
Argument `--help` lists all available options.
127170

128-
To install Orange with [winget](https://docs.microsoft.com/en-us/windows/package-manager/winget/), run:
171+
To run tests, use `unittest Orange.tests Orange.widgets.tests`
172+
173+
174+
### Setting up for development of all components
175+
176+
Should you wish to contribute Orange's base components (the widget base and the canvas), you must also clone these two repositories from Github instead of installing them as dependencies of Orange3.
177+
178+
First, fork all the repositories to which you want to contribute.
179+
180+
Set your GitHub username,
129181

130182
```Shell
131-
winget install --id UniversityofLjubljana.Orange
183+
export MY_GITHUB_USERNAME=replaceme
132184
```
133185

134-
### Starting Orange GUI
135-
136-
To start Orange GUI from the command line, run:
186+
create a conda environment, clone your forks, and install them:
137187

138188
```Shell
139-
orange-canvas
140-
# or
141-
python3 -m Orange.canvas
189+
conda create python=3 --yes --name orange3
190+
conda activate orange3
191+
192+
git clone ssh://git@github.com/$MY_GITHUB_USERNAME/orange-widget-base
193+
pip install -e orange-widget-base
194+
195+
git clone ssh://git@github.com/$MY_GITHUB_USERNAME/orange-canvas-core
196+
pip install -e orange-canvas-core
197+
198+
git clone ssh://git@github.com/$MY_GITHUB_USERNAME/orange3
199+
pip install -e orange3
200+
201+
# Repeat for any add-on repositories
142202
```
143203

144-
Append `--help` for a list of program options.
204+
It's crucial to install `orange-base-widget` and `orange-canvas-core` before `orange3` to ensure that `orange3` will use your local versions.

0 commit comments

Comments
 (0)