diff --git a/doc/Installation.md b/doc/Installation.md index 5e86a8e7..163cf59f 100644 --- a/doc/Installation.md +++ b/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`. diff --git a/doc/conf.py b/doc/conf.py index df28633d..6dc536fa 100644 --- a/doc/conf.py +++ b/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" diff --git a/pyproject.toml b/pyproject.toml index a4458a3d..caf66abd 100644 --- a/pyproject.toml +++ b/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"]