From 302f20a628b50e2d9cbc391ae7447c73d648c707 Mon Sep 17 00:00:00 2001 From: Chad Smith Date: Sat, 20 Apr 2019 09:34:27 -0700 Subject: [PATCH 1/2] add pipx installation instructions and prefer venv --- docs/install.rst | 61 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 502148ed..e10d136e 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -3,25 +3,48 @@ Installing Pelican Pelican currently runs best on |min_python|; earlier versions of Python are not supported. -You can install Pelican via several different methods. The simplest is via Pip_:: +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 `_:: python -m pip install pelican -Or, if you plan on using Markdown:: +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. - python -m pip install "pelican[markdown]" +**Recommended method 1:** `pipx `_ -(Keep in mind that some operating systems will require you to prefix the above -command with ``sudo`` in order to install Pelican system-wide.) +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:: -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:: + $ 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! ✨ 🌟 ✨ - virtualenv ~/virtualenvs/pelican - cd ~/virtualenvs/pelican - source bin/activate +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 ``python -m pip install pelican`` as noted above. Alternatively, if you @@ -35,8 +58,7 @@ version of Pelican rather than a stable release, use the following command:: python -m 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 ----------------- @@ -52,6 +74,11 @@ installed:: python -m 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 +112,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 ------------------- @@ -118,5 +149,5 @@ content):: The next step is to begin to adding content to the *content* folder that has been created for you. -.. _Pip: https://pip.pypa.io/ .. _virtualenv: https://virtualenv.pypa.io/en/latest/ +.. _venv: https://docs.python.org/3/library/venv.html From 8ad4e90170f1801c63e89ffe1d16d63304165da9 Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Mon, 29 Dec 2025 11:50:02 +0100 Subject: [PATCH 2/2] docs: Overhaul installation instructions; add `uv` --- docs/install.rst | 94 +++++++++++++++++++++++++----------------------- 1 file changed, 50 insertions(+), 44 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index e10d136e..c85e401f 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,62 +1,59 @@ Installing Pelican ################## -Pelican currently runs best on |min_python|; earlier versions of Python are not supported. +Pelican currently runs best on Python |min_python|; 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 `_:: +You can install Pelican via several different methods. - python -m pip install pelican +**Recommended method:** `Pip `_ User Install -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. +To install Pelican via Pip:: -**Recommended method 1:** `pipx `_ + python3 -m pip install --user "pelican[markdown]" -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:: +Or, if you do not plan to use `Markdown `_, +you can omit the ``[markdown]`` suffix:: - $ 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! ✨ 🌟 ✨ + python3 -m pip install --user pelican -To upgrade or uninstall:: +**Alternate method 1:** `Pipx `_ - pipx upgrade pelican - pipx uninstall pelican +Pipx lets you execute binaries from Python packages in isolated environments. +You can install Pipx by following its +`documentation `_. After Pipx is installed, +you can install Pelican via:: -**Recommended method 2:** Virtual Environment + pipx install "pelican[markdown]" -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.:: +**Alternate method 2:** `uv `_ - python -m venv ~/virtualenvs/pelican - . ~/virtualenvs/pelican/bin/activate +Like Pipx, ``uv`` allows you to install tools in isolated environments. +If you have ``uv`` installed, you can install Pelican via:: -Once the virtual environment has been created and activated, Pelican can be -installed via ``python -m pip install pelican`` as noted above. Alternatively, if you -have the project source, you can install Pelican using the setuptools method:: + uv tool install "pelican[markdown]" + +**Alternate method 3:** Virtual Environment + +If you prefer to manually manage a virtual environment, you can create +a virtual environment for Pelican via venv_ before installing Pelican:: + + python3 -m venv ~/virtualenvs/pelican + source ~/virtualenvs/pelican/bin/activate + python3 -m pip install "pelican[markdown]" + +Alternatively, if you have the project source, you can replace the last command +with the following to install Pelican using the ``setuptools`` method:: cd path-to-Pelican-source - python -m pip install . + python3 -m pip install . If you have Git installed and prefer to install the latest bleeding-edge version of Pelican rather than a stable release, use the following command:: - python -m pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican" + python3 -m pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican" To exit the virtual environment, type ``deactivate``. @@ -66,18 +63,23 @@ Optional packages If you plan on using `Markdown `_ as a markup format, you can install Pelican with Markdown support:: - python -m pip install "pelican[markdown]" + python3 -m pip install --user "pelican[markdown]" Typographical enhancements can be enabled in your settings file, but first the -requisite `Typogrify `_ library must be +requisite `Typogrify `_ library must be installed:: - python -m pip install typogrify + python3 -m pip install --user typogrify -If you are using pipx, you can inject packages into the pipx-managed virtual -environment:: +If you are using Pipx, you can inject packages into the Pipx-managed virtual +environment. For example, to add Typogrify:: - pipx inject pelican Markdown + pipx inject pelican typogrify + +To use ``uv`` to install Pelican with additional extra packages, use the +following example command, which like above will also install Typogrify:: + + uv tool install --with typogrify "pelican[markdown]" Dependencies ------------ @@ -107,15 +109,19 @@ Upgrading If you installed a stable Pelican release via Pip_ and wish to upgrade to the latest stable release, you can do so by adding ``--upgrade``:: - python -m pip install --upgrade pelican + python3 -m pip install --upgrade pelican -If you installed Pelican via distutils or the bleeding-edge method, simply +If you installed Pelican via ``setuptools`` or the bleeding-edge method, perform the same step to install the most recent version. -If you installed with pipx:: +If you installed with Pipx, upgrade via:: pipx upgrade pelican +If you installed with ``uv``, upgrade via:: + + uv tool upgrade pelican + Kickstart your site -------------------