Skip to content

Commit 6a03586

Browse files
jorgepilotojorgepiloto
committed
Add setup section
1 parent 862329c commit 6a03586

File tree

1 file changed

+392
-0
lines changed

1 file changed

+392
-0
lines changed

‎doc/source/how-to/setup.rst

Lines changed: 392 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,392 @@
1+
Development Environment
2+
=======================
3+
Before starting contributing to any ``PyAnsys`` projects, you will need to setup
4+
your developers environment.
5+
6+
Python
7+
------
8+
All ``PyAnsys`` projects require from a Python interpreter in order to interact
9+
with the software. Therefore, you want to make sure that at least one Python
10+
interpreter is installed in your local machine.
11+
12+
Installation
13+
~~~~~~~~~~~~
14+
There are multiple ways to install Python in your local machine:
15+
16+
- Using an official installer from the `official Python download section <https://www.python.org/downloads/>`_.
17+
- Installing it via a package manager or "store" in your machine.
18+
19+
.. warning::
20+
21+
Please, make sure you install Python from an official channel. Do not trust
22+
third party websites nor download executable content from those.
23+
24+
.. tabs::
25+
26+
.. group-tab:: Windows
27+
28+
To install Python in a machine using Windows, follow these steps:
29+
30+
1. Download the `latest stable Python version for Windows <https://www.python.org/downloads/windows/>`_.
31+
2. Execute the installer and follow the different steps.
32+
33+
For a more detailed installation process, please check `Using Python on
34+
Windows <https://docs.python.org/3/using/windows.html>`_.
35+
36+
.. group-tab:: macOS
37+
38+
To install Python in a machine using macOS, follow these steps:
39+
40+
1. Download the `latest stable Python version for macOS <https://www.python.org/downloads/macos/>`_.
41+
2. Execute the installer and follow the different steps.
42+
43+
For a more detailed installation process, please check `Using Python on
44+
a Mac <https://docs.python.org/3/using/mac.html>`_.
45+
46+
.. note::
47+
48+
It is likely that your macOS distribution already comes with some
49+
Python version installed. Please, refer to :ref:`Verify Installation`.
50+
51+
.. group-tab:: Linux/UNIX
52+
53+
To install Python in a machine using Linux/UNIX, follow these steps:
54+
55+
1. Download the `latest stable Python version for Linux/UNIX <https://www.python.org/downloads/source/>`_.
56+
2. Decompress the source code and follow the installation instructions in README.rst.
57+
58+
For a more detailed installation process, please check `Using Python on
59+
Unix Platforms <https://docs.python.org/3/using/unix.html>`_.
60+
61+
.. note::
62+
63+
It is likely that your Linux/UNIX distribution already comes with some
64+
Python version installed. Please, refer to :ref:`Verify Installation`.
65+
66+
67+
Verify Installation
68+
~~~~~~~~~~~~~~~~~~~
69+
Once your installation process is complete, verify your Python installation by
70+
running:
71+
72+
.. tabs::
73+
74+
.. group-tab:: Windows CMD
75+
76+
.. code-block:: text
77+
78+
py --version
79+
80+
.. group-tab:: Windows PowerShell
81+
82+
.. code-block:: text
83+
84+
py --version
85+
86+
.. group-tab:: macOS
87+
88+
.. code-block:: text
89+
90+
python --version
91+
92+
.. group-tab:: Linux/UNIX
93+
94+
.. code-block:: text
95+
96+
python --version
97+
98+
99+
Virtual Environments
100+
--------------------
101+
When working in multiple Python projects, it is likely each one of those has its
102+
own requirements. Sometimes, it may be possible that these requirements are
103+
incompatible across projects. To isolate Python environments and guarantee that
104+
no dependency problems are faced when workin with multiple projects, virtual
105+
environments were devised.
106+
107+
This subsection collects the most fundamental command for manipulating and
108+
interacting with Python virtual environments. For more information about these,
109+
please refer to `official Python documentation on venv module
110+
<https://docs.python.org/3/library/venv.html>`_.
111+
112+
Check
113+
~~~~~
114+
Before creating a new virtual environment, you need to check if you are already
115+
working with one. To do so, run the following command:
116+
117+
.. tabs::
118+
119+
.. group-tab:: Windows CMD
120+
121+
.. code-block:: text
122+
123+
where.exe python
124+
125+
.. group-tab:: Windows PowerShell
126+
127+
.. code-block:: text
128+
129+
where.exe python
130+
131+
.. group-tab:: macOS
132+
133+
.. code-block:: text
134+
135+
which python
136+
137+
.. group-tab:: Linux/UNIX
138+
139+
.. code-block:: text
140+
141+
which python
142+
143+
Previous command will return the path to the currently used Python environment
144+
in your system.
145+
146+
Make sure it points towards your default installation and not towards a virtual
147+
environment. If this is the case, then refer to :ref:`Deactivate` section to
148+
deactivate your virtual environment.
149+
150+
Create
151+
~~~~~~
152+
To create a virtual environment named `<venv>`, execute the following command:
153+
154+
.. tabs::
155+
156+
.. group-tab:: Windows CMD
157+
158+
.. code-block:: text
159+
160+
py -m venv <venv>
161+
162+
.. group-tab:: Windows PowerShell
163+
164+
.. code-block:: text
165+
166+
py -m venv <venv>
167+
168+
.. group-tab:: macOS
169+
170+
.. code-block:: text
171+
172+
python -m venv <venv>
173+
174+
.. group-tab:: Linux/UNIX
175+
176+
.. code-block:: text
177+
178+
python -m venv <venv>
179+
180+
Usually, virtual environments are named as ``venv`` or ``.venv``.
181+
182+
Activate
183+
~~~~~~~~
184+
To activate a virtual environment, execute the following command:
185+
186+
.. tabs::
187+
188+
.. group-tab:: Windows CMD
189+
190+
.. code-block:: text
191+
192+
<venv>\Scripts\activate.bat
193+
194+
.. group-tab:: Windows PowerShell
195+
196+
.. code-block:: text
197+
198+
<venv>\Scripts\Activate.ps1
199+
200+
.. group-tab:: macOS
201+
202+
.. code-block:: text
203+
204+
source <venv>/bin/activate
205+
206+
.. group-tab:: Linux/UNIX
207+
208+
.. code-block:: text
209+
210+
source <venv>/bin/activate
211+
212+
Deactivate
213+
~~~~~~~~~~
214+
215+
.. tabs::
216+
217+
.. group-tab:: Windows CMD
218+
219+
.. code-block:: text
220+
221+
deactivate
222+
223+
.. group-tab:: Windows PowerShell
224+
225+
.. code-block:: text
226+
227+
deactivate
228+
229+
.. group-tab:: macOS
230+
231+
.. code-block:: text
232+
233+
deactivate
234+
235+
.. group-tab:: Linux/UNIX
236+
237+
.. code-block:: text
238+
239+
deactivate
240+
241+
242+
Git
243+
---
244+
`Git <https://git-scm.com/>`_ is an open-source version control system (VCS). It
245+
is used to track changes and register new ones in software related projects.
246+
247+
Installation
248+
~~~~~~~~~~~~
249+
250+
.. tabs::
251+
252+
.. group-tab:: Windows
253+
254+
To install Python in a machine using Windows, follow these steps:
255+
256+
1. Download the `latest stable standalone Git version for Windows <https://www.python.org/downloads/win/>`_.
257+
2. Execute the installer and follow the different steps.
258+
259+
.. group-tab:: macOS
260+
261+
To install Python in a machine using macOS, follow these steps:
262+
263+
1. Check the `latest stable Git version for macOS <https://git-scm.com/download/mac>`_.
264+
2. Run the installation command for your package manager.
265+
266+
.. group-tab:: Linux/UNIX
267+
268+
To install Git in a machine using Linux/UNIX, follow these steps:
269+
270+
1. Check the `latest stable Git version for Linux/UNIX <https://git-scm.com/download/linux>`_.
271+
2. Run the installation command for your package manager.
272+
273+
274+
Verify Installation
275+
~~~~~~~~~~~~~~~~~~~
276+
Check if the installation process succeeded by running the following command:
277+
278+
.. tabs::
279+
280+
.. group-tab:: Windows CMD
281+
282+
.. code-block:: text
283+
284+
git --version
285+
286+
.. group-tab:: Windows PowerShell
287+
288+
.. code-block:: text
289+
290+
git --version
291+
292+
.. group-tab:: macOS
293+
294+
.. code-block:: text
295+
296+
git --version
297+
298+
.. group-tab:: Linux/UNIX
299+
300+
.. code-block:: text
301+
302+
git --version
303+
304+
Usage
305+
~~~~~
306+
If you are not familiar with this tool and would like to know how to use it,
307+
please refer to the `Git Reference Manual <https://git-scm.com/doc>`_. In
308+
previous website, you will find plenty of resources for learning Git.
309+
310+
Configuration
311+
~~~~~~~~~~~~~
312+
.. todo::
313+
314+
315+
Signing Commits
316+
~~~~~~~~~~~~~~~
317+
.. todo::
318+
319+
Enabling SSH
320+
~~~~~~~~~~~~
321+
.. todo::
322+
323+
324+
WSL2
325+
----
326+
Some developers prefer using Windows as the operative system for their machines.
327+
However, they may like to take advantage from some features provided by a Linux
328+
system. To solve for this problem, the `Windows Subsystem for Linux
329+
<https://docs.microsoft.com/en-us/windows/wsl/install>`_ was devised.
330+
331+
Installation
332+
~~~~~~~~~~~~
333+
Open a new PowerShell session and enter the following command:
334+
335+
.. code-block:: powershell
336+
337+
wsl --install
338+
339+
After installing ``WSL``, make sure you are running the ``WSL2`` version by
340+
executing:
341+
342+
.. code-block:: powershell
343+
344+
wsl --set-default-version 2
345+
346+
Verifying Installation
347+
~~~~~~~~~~~~~~~~~~~~~~
348+
To check which ``WSL`` version are you using, run:
349+
350+
.. code-block:: powershell
351+
352+
wsl --list -v
353+
354+
Installing a Linux Distro
355+
~~~~~~~~~~~~~~~~~~~~~~~~~
356+
Once ``WSL2`` has been installed, it is time to install a Linux
357+
distribution. To get a list of the available ones, run:
358+
359+
.. code-block:: powershell
360+
361+
wsl --list --online
362+
363+
Most developers choose `Ubuntu <https://ubuntu.com/download>`_, as it is a
364+
heavily maintained Linux distribution with a huge collection of packages.
365+
366+
Proceed to install the Linux distribution of your choice by running:
367+
368+
.. code-block:: powershell
369+
370+
wsl --install -d <distro name>
371+
372+
You can install multiple Linux distributions by running previous command. To
373+
indicate ``WSL2`` which distribution you would like to use, execute:
374+
375+
.. code-block:: powershell
376+
377+
wsl -d <distro name>
378+
379+
380+
Windows Terminal
381+
----------------
382+
The `Windows Terminal <https://docs.microsoft.com/en-us/windows/terminal/>`_ is
383+
an application devised to integrate in a single console multiple shells.
384+
Considering that Windows ships by default with two shells (``CMD`` and
385+
``PowerShell``) and that installing :ref:`WSL2` adds a third one, ``Windows
386+
Terminal`` allows to collect all of them in a single program.
387+
388+
Installation
389+
~~~~~~~~~~~~
390+
You can install `Windows Terminal from Microsoft Store
391+
<https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701?hl=en-us&gl=US>`_
392+
directly from the Windows Store.

0 commit comments

Comments
 (0)