Skip to content

Commit

Permalink
Docs: simplified installation instructions (#567)
Browse files Browse the repository at this point in the history 
Also:
- improved contributing instructions
- updated deps (including fix for pytest-benchmark compatibility with pytest 7.2)
  • Loading branch information
@abey79
abey79 authored Oct 25, 2022
1 parent 9619919 commit 18de0ef
Show file tree
Hide file tree
Showing 6 changed files with 167 additions and 240 deletions.
4 changes: 2 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@ Release date: UNRELEASED
* The `layout` command now properly handles the `tight` special case by fitting the page size around the existing geometries, accommodating for a margin if provided (#556)
* Added new units (`yd`, `mi`, and `km`) (#541)
* Added `inch` unit as a synonym to `in`, useful for expressions (in which `in` is a reserved keyword) (#541)
* Migrated to PySide6 (from PySide2), which simplifies installation on Apple silicon Macs (#552, #559)
* Migrated to PySide6 (from PySide2), which simplifies installation on Apple silicon Macs (#552, #559, #567)

### Bug fixes

* Fixed a viewer issue where page width/height of 0 would lead to errors and a blank display (#555)
* Fixed a viewer issue where fitting the document bounds would be lost when bounds change (*vsketch* only) (#564)
* Fixed a viewer issue where fitting the view to the document would not adjust when page size changes (*vsketch* only) (#564)

### API changes

Expand Down
7 changes: 3 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -194,14 +194,13 @@ TL;DR:
```bash
pipx install "vpype[all]"
```
- Installing on M1 Mac requires special care — check the [installation instruction](https://vpype.readthedocs.io/en/latest/install.html#installing-using-pipx-apple-silicon-m1).
- A Windows installer is available [here](https://github.com/abey79/vpype/releases) (plug-ins cannot be installed
when using this installation method).
- A Windows installer is available [here](https://github.com/abey79/vpype/releases), but plug-ins cannot be installed
when using this method).
- A CLI-only version of *vpype* can be installed using the following command:
```bash
pipx install vpype
```
This version does not include the [`show`](https://vpype.readthedocs.io/en/latest/reference.html#show) command but does not require some of the dependencies which are more difficult or impossible to install on some platforms (such as matplotlib, PySide2, and ModernGL).
This version does not include the [`show`](https://vpype.readthedocs.io/en/latest/reference.html#show) command but does not require some of the dependencies which are more difficult or impossible to install on some platforms (such as matplotlib, PySide6, and ModernGL).


## Documentation
Expand Down
21 changes: 11 additions & 10 deletions docs/contributing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Contributions are most welcome and there are many ways you can help regardless

* First and foremost, do provide feedback on what you do with *vpype* and how you do it, either on the `DrawingBots Discord server`_ or by filling an `issue`_. This knowledge is critically important to improve *vpype*.
* Write an `issue`_ for any problem or friction point you encounter during the installation or use of *vpype* or for any feature you feel is missing.
* Make the present documentation better by fixing typos and improve the quality of the text (English is *not* the main author's native language).
* Make the present documentation better by fixing typos and improve the quality of the text (English is *not* the main author's native language). `This issue <https://github.com/abey79/vpype/issues/400>`__ maintains a list of possible improvements.
* Write cookbook recipes for new workflows.
* Improving the test coverage and contributing to CI/CD aspects is welcome — and a good way to become familiar with the code.
* Improve existing features or contribute entirely new ones with a `pull request`_. If you plan on creating new commands, consider making a :ref:`plugin <plugins>` first — it will be easy to integrate it into *vpype*'s codebase later on if it makes sense.
Expand Down Expand Up @@ -40,33 +40,34 @@ Development environment
<https://python-poetry.org/docs/#installation>`_ is required to prepare the development environment. It can be
installed either using an install script, or using pipx. Run this command to use the install script::

$ curl -sSL https://install.python-poetry.org | python3 -
curl -sSL https://install.python-poetry.org | python3 -
Run this command for a pipx install::

$ pipx install poetry
pipx install poetry

See Poetry's `installation instructions <https://python-poetry.org/docs/#installation>`__ for more information.

You can then download *vpype*, prepare a virtual environment and install all dependencies with a few commands::

$ git clone https://github.com/abey79/vpype.git
$ cd vpype
$ poetry install -E all
git clone https://github.com/abey79/vpype
cd vpype
poetry install -E all --with docs

You can execute *vpype* (which installed in the project's virtual environment managed by Poetry) with the ``poetry
run`` command::

$ poetry run vpype --help
poetry run vpype --help

Alternatively, you can activate the virtual environment and then directly use *vpype*::

$ poetry shell
$ vpype --help
poetry shell
vpype --help

Running the tests
=================

You can run tests with the following command::

$ poetry run pytest
poetry run pytest

198 changes: 58 additions & 140 deletions docs/install.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,152 +9,70 @@ This page explain how to install *vpype* for end-users. If you intend to develop

.. note::

The recommended Python version is 3.10.2 or later (except for macOS/M1 computer, for which Python 3.9 is recommended). *vpype* is also compatible with Python 3.8 and 3.9.
The recommended Python version is 3.10.2 or later. *vpype* is also compatible with Python 3.8 and 3.9.

..
Overview
========
.. warning::

This table provides an overview of the available methods to install *vpype*. The recommended method is using `pipx`_.

.. csv-table::
:header: Installation Method, macOS, Windows, Linux, Note
:widths: 12, 5, 5, 5, 18

`pipx`_, ✅ , ✅, ✅, "| ✅ recommended method
| ⚠️ see instruction for macOS/M1"
`pip`_ (global installation), ✅, ✅, ✅, ⚠️⚠️⚠️ **strongly discouraged**
`pip`_ (virtual environment), ✅, ✅, ✅, a virtual environment must be manually created *and* activated
installer, 🚫, ✅, 🚫, does not support plug-ins
`MacPorts`_, ✅️, 🚫, 🚫, ⚠️ plug-ins must be installed globally (not recommended)

Installing Python and a Python-based package can be overwhelming for new users. The following glossary shortly defines a few of the key terms and notions.

Python interpreter
Any Python-based package needs a Python interpreter to be executed. A major version of the Python interpreter is released every year. The current one is the Python 3.10 series. In general, using the latest version is recommended but using an older version is sometime necessary. For example, *vpype* requires Python 3.9 to run on macOS/M1 computers.

`pip`_
`pip`_ is the fundamental tool to download and install publicly-available packages like *vpype*. These package are stored in the `Python Package Archive <PyPI>`_ where they can be found by pip. pip automatically download and install all the dependencies required by the package.

Global installation
By default, pip installs packages globally, next to the Python interpreter. Such package become available to all users and software on the computer. Although doing so may sound reasonable, it is in general strongly discouraged because of the very likely risk of conflicts when different packages relies on different version of the same dependencies.

`Virtual Environments <venv>`_
To avoid the conflict issue, packages and their dependencies, a `virtual environments <venv>`_ may be created. They behave like isolated, self-contained directory which contains both the Python interpreter, the desired package, and its dependencies. Multiple virtual environments can be used for different tasks, avoiding all risks of conflicts. When using `pip`_, packages will be installed in a given virtual environment *if (and only if)* said virtual environment was previously activated (activating a virtual environment makes its content available to the current terminal session). Managing and using virtual environments can either be done manually (using the `venv`_ standard Python package), or can be done automatically using some high-level tool.

`pipx`_
`pipx`_ is such a high-level tool and is made to install Python-based CLI software such as *vpype*. Specifically, it automates two important tasks: (1) it automatically creates and manages a virtual environment for every software installed with it and (2) it ensures that the installed software is in the path and thus available in terminal windows.

`MacPorts`_
`MacPorts`_ is a package manager dedicated to the installation of various open-source software and libraries on the Mac platform. It is similar to the packages manager typically found in Linux distributions.
*vpype* is not yet compatible with Python 3.11.


macOS
=====

.. caution::

**macOS/M1 note**: Due to the restricted availability of an ARM-compatible PySide2 library, installing *vpype* on a macOS/M1 computers requires the specific steps described bellow. Using alternative ways to install Python and *vpype* may work, but typically don't and are thus discouraged.

.. highlight:: bash

`MacPorts`_ is the recommended way to install the Python interpreter on macOS.

Following the `installation instructions <https://www.macports.org/install.php>`__ to install MacPorts. Then, make sure its port database is up-to-date::

$ sudo port selfupdate
$ sudo port upgrade outdated


Installing using the MacPorts port
----------------------------------

.. note::

Although this is the easiest way to install *vpype*, it is discouraged when using :ref:`plug-ins <plugins>` because they would have to be globally installed.

Installing *vpype* using the port can be done with the following command::

$ sudo port install vpype

This installation method works for both Intel- and M1-based Macs.

Installing Python
-----------------

Installing using pipx (Apple silicon/M1)
----------------------------------------
The official installer is the recommended way to install Python on your computer. It can be downloaded `here <https://www.python.org/downloads/>`__.

Installing *vpype* on Macs with Apple Silicon requires specific steps because some its dependencies are not yet fully supported on this architecture. Using `pipx`_ is the recommended method when using plug-ins.

First, install the required ports using MacPorts::

$ sudo port install python39 py39-shapely py39-scipy py39-numpy py39-pyside2

Then, install pipx::

$ sudo port install pipx +python39
$ pipx ensurepath

The second command above ensures that both pipx and the software it will install are available the terminal. You may need to close and re-open the terminal window for this to take effect.
.. caution::

Finally, install *vpype*::
When install Python, make sure to select version that is compatible with *vpype*. See the :doc:`top of this page <install>` for more information.

$ pipx install "vpype[all]" --system-site-packages

Note the use of the ``--system-site-packages`` option. This is important because because *vpype* relies the version of PySide2 that was installed earlier with MacPort.
You can ensure that the installed Python interpreter is properly installed by running this command::

*vpype* should now be installed and ready to use. You may check that it is fully functional by checking its version and displaying some random lines::
python3 --version

$ vpype --version
vpype 1.9.0
$ vpype random show
It should produce an output similar to::

Python 3.10.8

Installing using pipx (Intel)
-----------------------------
The version number should match the installer you used.

.. note::
Note that installing Python from `Homebrew <https://brew.sh>`__ or `MacPorts`_ is possible as well.

The instructions for Apple silicon/M1 Macs also apply, but since dependencies have better support for Intel-based Macs, some steps may be simplified.

First, install pipx::
Installing pipx
---------------

$ sudo port install pipx
$ pipx ensurepath
The second command above ensures that both pipx and the software it will install are available the terminal. You may need to close and re-open the terminal window for this to take effect.
`pipx`_ is a tool that allows you to install Python applications in isolated environments. It is the recommended way to install *vpype* on macOS. It can be installed with the following commands::

Then, install *vpype*::
python3 -m pip install pipx
python3 -m pipx ensurepath

$ pipx install "vpype[all]"
After this, restart your terminal and ensure that pipx is properly installed by running this command::

*vpype* should now be installed and ready to use. You may check that it is fully functional by checking its version and displaying some random lines::
pipx --version

$ vpype --version
vpype 1.9.0
$ vpype random show
It should print out the current version of pipx without error::

1.1.0

Installing using pipx and the official Python distribution
----------------------------------------------------------

For Intel-based Macs, the official Python distribution may be used as an alternative to MacPorts. It can be downloaded from the `official Python website <https://www.python.org/downloads/>`_.
Installing *vpype*
------------------

After running the Python installer, install pipx with the following command::
Once pipx is properly installed, you can install *vpype* with the following command::

$ sudo python3 -m pip install pipx
$ pipx ensurepath
pipx install "vpype[all]"

The second command above ensures that both pipx and the software it will install are available the terminal. You may need to close and re-open the terminal window for this to take effect.
*vpype* should now be installed and ready to use. You may check that it is fully functional by checking its version or displaying some random lines::

Then, install *vpype*::

$ pipx install "vpype[all]"

*vpype* should now be installed and ready to use. You may check that it is fully functional by checking its version and displaying some random lines::

$ vpype --version
vpype 1.9.0
$ vpype random show
vpype --version
vpype random show


Windows
Expand All @@ -165,88 +83,88 @@ Windows
Installing using the installer
------------------------------

A Windows installer for *vpype* is `available here <https://github.com/abey79/vpype/releases>`__. Although this installation method is the easiest, it **does not** allow plug-ins to be installed. If plug-ins are required, installing using pipx is recommended.
A Windows installer for *vpype* is `available here <https://github.com/abey79/vpype/releases>`__. Although this installation method is the easiest, it **does not** allow :doc:`plug-ins <plugins>` to be installed. If plug-ins are required, installing using pipx is recommended.

Installing using pipx
---------------------

First, Python must be installed. Python 3.10 is recommended, although *vpype* it is also compatible with Python 3.8 and later. The official Python distribution for Windows can be `downloaded here <https://www.python.org/downloads/>`__ or installed from the `App Store <https://www.microsoft.com/en-us/p/python-310/9pjpw5ldxlz5>`_. When installing Python, make sure you enable adding Python to the path.
First, install Python. The official Python distribution for Windows can be `downloaded here <https://www.python.org/downloads/>`__ or installed from the `App Store <https://www.microsoft.com/en-us/p/python-310/9pjpw5ldxlz5>`_. When installing Python, make sure you enable adding Python to the path.

.. caution::

When install Python, make sure to select version that is compatible with *vpype*. See the :doc:`top of this page <install>` for more information.

First, install pipx::
Then, install pipx::

> python -m pip install --user pipx
> pipx ensurepath
python -m pip install --user pipx
pipx ensurepath

In the first command, replace ``python`` by ``python3`` if you installed Python from the App Store. The second command above ensures that both pipx and the software it will install are available the terminal. You may need to close and re-open the terminal for this to take effect.

Then, install *vpype*::
Finally, install *vpype*::

> pipx install "vpype[all]"
pipx install "vpype[all]"

*vpype* should now be installed and ready to use. You may check that it is fully functional by checking its version and displaying some random lines::

> vpype --version
vpype 1.9.0
> vpype random show
vpype --version
vpype random show

Linux
=====

.. highlight:: bash

First, install `pipx`_ with your system's package manager. On Debian/ubuntu flavored installation, this is typically done as follows::
First, install `pipx`_ with your system's package manager. On Debian/Ubuntu flavored installation, this is typically done as follows::

$ sudo apt-get install pipx
sudo apt-get install pipx

Then run the following command to ensure your path variable is properly set::

$ pipx ensurepath
pipx ensurepath

You may need to close and re-open the terminal window for this to take effect.

Finally, install *vpype*::

$ pipx install "vpype[all]"
pipx install "vpype[all]"

*vpype* should now be installed and ready to use. You may check that it is fully functional by checking its version and displaying some random lines::

$ vpype --version
vpype 1.9.0
$ vpype random show

vpype --version
vpype random show


Raspberry Pi
============

Full installation including the viewer on the Raspberry Pi is no longer supported. Expert users may succeed with ``pip install vpype[all]`` provided that a suitable version of the PySide2 package is available. Also, the new viewer requires OpenGL 3.3, which the Raspberry Pi does not support. The classic viewer should work correctly::
Full installation including the viewer on the Raspberry Pi is no longer supported. Expert users may succeed with ``pipx install "vpype[all]"``. Also, the new viewer requires OpenGL 3.3, which the Raspberry Pi does not support. The classic viewer should work correctly::

$ vpype [...] show --classic
vpype [...] show --classic

Installing the CLI-only version described in the next section is easier and should be favored whenever possible. Here are the recommended steps to do so.

Some packages and their dependencies are easier to install at the system level::

$ sudo apt-get install python3-shapely python3-numpy python3-scipy
sudo apt-get install python3-shapely python3-numpy python3-scipy

Then, install pipx::

$ sudo apt-get install pipx
$ pipx ensurepath
sudo apt-get install pipx
pipx ensurepath

Finally, install and run *vpype*::

$ pipx install vpype
$ vpype --version
vpype 1.9.0
pipx install vpype
vpype --version


CLI-only install
================

For special cases where the :ref:`cmd_show` is not needed and dependencies such as matplotlib, PySide2, or ModernGL are difficult to install, a CLI-only version of *vpype* can be installed using this command::
For special cases where the :ref:`cmd_show` is not needed and dependencies such as matplotlib, PySide6, or ModernGL are difficult to install, a CLI-only version of *vpype* can be installed using this command::

$ pipx install vpype
pipx install vpype

Note the missing ``[all]`` compared the instructions above.

Expand Down
Loading

0 comments on commit 18de0ef

Please sign in to comment.