docs: Add Pipx & uv as alternate install methods

[justinmayer]

Pip and virtual environments can pose Pelican installation challenges for newcomers, so these changes include recommendations for Pipx and uv to facilitate installing Pelican.

Resolves: #3536

See also: #2560

[Dreamsorcerer]

Personally, I'd still use the approach that involves the least effort for users, rather than recommending them to first install other software just to install this one.

e.g.

On a Linux system (such as Ubuntu), Pelican may already be packaged in your distro, in which case you can install it with the usual install command. e.g. On Ubuntu:
sudo apt install pelican

Otherwise, you can install the latest version via pip using:
python -m pip install --user pelican

(If the python command is unavailable on your system, you'll first need to install it: https://realpython.com/installing-python/).

[justinmayer]

Thank you for sharing your thoughts, Sam. I made a few follow-up changes:

• Pip user install is now listed as the first recommended method.
• python3 is now used instead of python (latter is not always available).

I am not inclined to mention distro packaging. Distro package versions can often lag behind the latest Pelican release, which can lead to users filing issues that have already been resolved in shipped releases. Folks who are already aware of this trade-off can, of course, choose to install via their distro’s package manager anyway.

[boxydog]

Documenting initial install is a hard problem, because there's so little you can rely on.

I'm going to respond as requested, but I think my proposals are not what you want.

First, having 4 recommended methods seems bad. Harder to understand, harder to maintain. I just want one. At the very least you could describe other methods, but not say they are "recommended"; preferably I'd just ditch them. Now, people install in different ways, and they all want their own method, so do with this what you will.

Second, I'd choose the venv/python method, because it's the only one that doesn't require further install (they are both already in python3 through -m).

It looks like you moved away from this (perhaps due to #3536?), but wouldn't venv would fix that?

[justinmayer]

Thank you for the input, @boxydog. I think the real fix for #3536 was the --user option that I added to the pip install pelican command. Yes, that problem could also be solved with a virtual environment, but looking at the number of steps required for each approach, it's not much of a comparison. The virtual environment approach requires more steps — compared to just a single command — and the user has to (1) wrap their head around the concept of virtual environments and (2) remember to activate said environment before invoking Pelican… each and every time.

That said, I agree that having four recommended methods is silly, so I changed that in my latest commit. Thanks again for the feedback!

[boxydog]

Nice adjustment. Looks good: 1 recommended method, a lot of other possibly useful info about other installers.

P.S. I'd be happy to do more for pelican, but it's not obvious to me what would be likely to help the most, so I don't. Always happy to do something if I can.

[pauloxnet]

I personally suggest in docs and articles only installation with pip and venv because they are part of the standard library and installing external packages are not required.

In addition if you are already a user of uv or pipx you will know how to use them to install a Python package I can't see the point to add these additional instructions in the documentation of a package, you need to maintain them during the time, with risks of broken outdated instructions.

Of course it's just my point of view.

[offbyone]

I think it might be worth making uv the recommended method; it solves so many of the possible permutations (python versions, dependency locks, etc).

If we do that, we can rewrite this with a whole bunch fewer variations:

• Basic install:

  1. install uv
  2. uv tool install pelican

• Optional packages:

  • uv tool install 'pelican[markdown]'

That gets rid of, like, all of this :D

[boxydog]

Now, people install in different ways, and they all want their own method, so do with this what you will.

:)

I'd still choose pip, since it's already installed, but I won't die on this hill. I do think it's good to have one recommended method, which you already did.

[minchinweb]

Thoughts:

• I'm not crazy about have 4 alternative installation methods listed side by side. Ideally, we would stick with one that would cover 95% of usecases.
  • partly this is because my plugins' documentation should support the officially recommended way to installing Pelican, and I'd rather not have to write it 4 different ways
• I think whatever method we pick needs to have a virtual environment, either explicitly or under the hood, as plugins (post v4.5) now get automatically loaded if they are installed.
  • I work on several Pelican sites on my same machine, all with slightly different plugin combinations, but I don't know how common that is
  • adding packages to a pipx install has always been a bit of a pain, but only because I can never remember how to properly add them (I think you can add them to the "spec", which is what you want, or can drop to pip directly)
  • with uv, it appears you can install additional packages into your tool install, but I've never tried it
  • personally, I'd probably use venv, but I've used it for so long I'm not sure if I'm missing how hard (or not) it is to set up for the first time.
• there is a philosophical question of whether to present Pelican a CLI script (and somewhat (or entirely) downplay the Python side) or to present Pelican at a Python library that you set up as a Python project. In the former, uv (or pipx) is a good presentation, but for the later, venv is probably more "proper".
• perhaps alternative installation methods could be moved to an "alternative install" methods page?

I don't feel hugely strongly about which method is presented as "blessed", just that it should be only one.

[justinmayer]

Many thanks to everyone who provided feedback on my effort to expand the installation documentation. I feel comfortable enough with these changes to merge and see how they work in practice. If it seems like it’s too much, I’m happy to pare it down a bit in the future.