Docs: simplified installation instructions (#567)

Also:
- improved contributing instructions
- updated deps (including fix for pytest-benchmark compatibility with pytest 7.2)

Author: abey79

CHANGELOG.md

@@ -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
 

README.md

@@ -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

docs/contributing.rst

@@ -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.
@@ -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
+

docs/install.rst

@@ -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
@@ -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.