Make the installation page more beginner friendly (#143)

Closes #140

doc/Installation.md

@@ -1,43 +1,67 @@
 # Installation
 
-## Using `pip`
+Please select one of the following installation methods that best suits your workflow.
+
+```{note}
+If you are a beginner in Python, please note that the commands below must be executed in a
+**terminal**, not in the _Python console_. This is indicated by the `$` or `C:>` prompt as opposed
+to the Python console prompt `>>>`.
+```
+
+## 1. Using `pip`
 
 `roseau-load-flow` is available on [PyPI](https://pypi.org/project/roseau-load-flow/). It can be
 installed using pip with:
 
-```console
-$ python -m pip install roseau-load-flow
+````{tab} Windows
+
+```doscon
+C:> python -m pip install roseau-load-flow
 ```
 
-`````{tip}
-It is recommended to work in a virtual environment to isolate your project. You can create one with:
+````
+
+````{tab} Linux/MacOS
 
 ```console
-$ python -m venv venv
+$ python -m pip install roseau-load-flow
 ```
 
-A folder named `venv` will be created. To activate the virtual environment, run:
+````
+
+`````{tip}
+It is recommended to work in a virtual environment to isolate your project. Create and activate a virtual environment before installing the package. You can create one with:
 
 ````{tab} Windows
 
 ```doscon
-C:> venv\Scripts\activate
+C:> python -m venv .venv
 ```
 
 ````
 
-````{tab} Linux
+````{tab} Linux/MacOS
 
 ```console
-$ source venv/bin/activate
+$ python -m venv .venv
+```
+
+````
+
+A folder named `.venv` will be created. To activate the virtual environment, run:
+
+````{tab} Windows
+
+```doscon
+C:> .venv\Scripts\activate
 ```
 
 ````
 
-````{tab} MacOS
+````{tab} Linux/MacOS
 
 ```console
-$ . venv/bin/activate
+$ source .venv/bin/activate
 ```
 
 ````
@@ -46,26 +70,63 @@ $ . venv/bin/activate
 
 To upgrade to the latest version (recommended), use:
 
+````{tab} Windows
+
+```doscon
+C:> python -m pip install --upgrade roseau-load-flow
+```
+
+````
+
+````{tab} Linux/MacOS
+
 ```console
 $ python -m pip install --upgrade roseau-load-flow
 ```
 
-Moreover, using the `pip` installation, some plot functions requires additional dependencies that are not installed by
-default. If you need these functions, you can install the `plot` extra using
+````
 
-```console
-$ python -m pip install roseau-load-flow[plot]
+Optional dependencies can be installed using the available extras. These are only needed if you use
+the corresponding functions. They can be installed with the
+`python -m pip install roseau-load-flow[EXTRA]` command where `EXTRA` is one of the following:
+
+1. `plot`: installs _matplotlib_ for the plotting functions
+2. `graph` installs _networkx_ for graph theory analysis functions
+
+## 2. Using `pip` in Jupyter Notebooks
+
+If you are using Jupyter Notebooks, you can install `roseau-load-flow` directly from a notebook
+cell with:
+
+```ipython3
+In [1]: %pip install roseau-load-flow
 ```
 
-## Using `conda`
+This installs the package in the correct environment for the active notebook kernel.
+
+## 3. Using `conda`
 
 `roseau-load-flow` is also available on [conda-forge](https://anaconda.org/conda-forge/roseau-load-flow).
 It can be installed using conda with:
 
+````{tab} Windows
+
+```doscon
+C:> conda install -c conda-forge roseau-load-flow
+```
+
+````
+
+````{tab} Linux/MacOS
+
 ```console
 $ conda install -c conda-forge roseau-load-flow
 ```
 
+````
+
+This installs the package and all its required and optional dependencies.
+
 ```{tip}
 If you use *conda* to manage your project, it is recommended to use the `conda` package manager
 instead of `pip`.

doc/conf.py

@@ -137,6 +137,9 @@
 # -- Options for sphinx_copybutton -------------------------------------------
 copybutton_exclude = ".linenos, .gp, .go"
 copybutton_copy_empty_lines = False
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html#strip-and-configure-input-prompts-for-code-cells
+copybutton_prompt_text = r">>> |\.\.\. |\$ |C:> |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
 
 # -- Options for sphinxcontrib.googleanalytics -------------------------------
 googleanalytics_id = "G-Y9QSN78RFV"

pyproject.toml

@@ -57,6 +57,7 @@ matplotlib = { version = ">=3.7.2", optional = true }
 networkx = { version = ">=3.0.0", optional = true }
 
 [tool.poetry.extras]
+# DO NOT forget to update the installation page in the documentation when extras change
 plot = ["matplotlib"]
 graph = ["networkx"]