From 9accf61c6c33593612a5200397540022ceb4fa3c Mon Sep 17 00:00:00 2001 From: Chad Smith Date: Sat, 20 Apr 2019 09:34:27 -0700 Subject: [PATCH] add pipx installation instructions and prefer venv --- docs/install.rst | 57 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 11 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 571de95e..9970abcd 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -4,22 +4,48 @@ Installing Pelican Pelican currently runs best on Python 2.7.x and 3.5+; earlier versions of Python are not supported. +Once Pelican is installed, you can run ``pelican --help`` to see basic usage +options. For more detail, refer to the :doc:`Publish` section. + You can install Pelican via several different methods. The simplest is via `pip `_:: pip install pelican -(Keep in mind that operating systems will often require you to prefix the above -command with ``sudo`` in order to install Pelican system-wide.) +Keep in mind that operating systems will often require you to prefix the above +command with ``sudo`` in order to install Pelican system-wide. **You should +not do this** as it may break your operating system. In this case you +can add the ``--user`` flag or try one of the recommended methods below. -While the above is the simplest method, the recommended approach is to create a -virtual environment for Pelican via virtualenv_ before installing Pelican. -Assuming you have virtualenv_ installed, you can then open a new terminal -session and create a new virtual environment for Pelican:: +**Recommended method 1:** `pipx `_ - virtualenv ~/virtualenvs/pelican - cd ~/virtualenvs/pelican - source bin/activate +pipx lets you execute binaries from Python packages in isolated environments. +You can install pipx according to instructions on its +`homepage `_. After pipx is installed, +you can install pelican:: + + $ pipx install pelican + installed package pelican 4.0.1, Python 3.6.7 + These binaries are now globally available + - pelican + - pelican-import + - pelican-quickstart + - pelican-themes + done! ✨ 🌟 ✨ + +To upgrade or uninstall:: + + pipx upgrade pelican + pipx uninstall pelican + +**Recommended method 2:** Virtual Environment + +If you prefer to manually manage a Virtual Environment, you can create +a virtual environment for Pelican via venv_ (or virtualenv_ if you are +using Python2) before installing Pelican.:: + + python -m venv ~/virtualenvs/pelican + . ~/virtualenvs/pelican/bin/activate Once the virtual environment has been created and activated, Pelican can be installed via ``pip install pelican`` as noted above. Alternatively, if you @@ -33,8 +59,7 @@ version of Pelican rather than a stable release, use the following command:: pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican" -Once Pelican is installed, you can run ``pelican --help`` to see basic usage -options. For more detail, refer to the :doc:`Publish` section. +To exit the virtual environment, type ``deactivate``. Optional packages ----------------- @@ -49,6 +74,11 @@ requisite `Typogrify `_ library must be installed:: pip install typogrify + +If you are using pipx, you can inject packages into the pipx-managed virtual +environment:: + + pipx inject pelican Markdown Dependencies ------------ @@ -85,6 +115,10 @@ the latest stable release, you can do so by adding ``--upgrade``:: If you installed Pelican via distutils or the bleeding-edge method, simply perform the same step to install the most recent version. +If you installed with pipx:: + + pipx upgrade pelican + Kickstart your site ------------------- @@ -112,3 +146,4 @@ The next step is to begin to adding content to the *content* folder that has been created for you. .. _virtualenv: http://www.virtualenv.org/ +.. _venv: https://docs.python.org/3/library/venv.html