search

greghendershott / frog

Frog is a static blog generator implemented in Racket, targeting Bootstrap and able to use Pygments.
918 stars 96 forks source link

Update Quick Start instructions for installing Pygments #225

Closed jbshirk closed 5 years ago

jbshirk commented 5 years ago

I ran into this trouble and thought someone would like to know about it, and how I worked around it. Essentially, ez_setup.py is deprecated. Evenually, a better way of getting Pygments will be needed.

https://github.com/pypa/setuptools/issues/738#issuecomment-409341311

greghendershott commented 5 years ago

Oh geez that sounds horrible.

I don't know very much about the Python ecosystem. Originally sudo easy_install --upgrade Pygments worked (as did sudo apt-get install python-setuptools if you didn't already have easy_install).

Looking at http://pygments.org/ it suggests pip install Pygments and links to https://pypi.org/project/Pygments/ which says the same.

I'm not sure how to get pip (which I don't seem to have at the moment). It looks like the tutorial for that is here: https://packaging.python.org/tutorials/installing-packages/

Maybe we should just link to those, instead?

greghendershott commented 5 years ago

For anyone coming across this issue, who might be hip to Python but not Frog: The status quo documentation this issue about is at here. An inline markdown rendering would be:

  1. Optional: Install Pygments if you want syntax highlighting for fenced code blocks:

    $ sudo easy_install --upgrade Pygments

    Why --upgrade? You probably want the most recent version of Pygments because new languages are constantly being added. For example, Racket is supported starting in Pygments 1.6.

    If that fails, try again after installing easy_install:

    $ sudo apt-get install python-setuptools

If anyone knowledgeable wants to suggest new text, of course I can handle Scribble-izing it into final form.

jbshirk commented 5 years ago

While I was researching this problem, I ran into a lot of advisements that pip is terrible at tracking versions. All of those people recommended avoiding that in favor of just about any other method. I think the shell dump I posted shows that happening.

greghendershott commented 5 years ago

Sorry -- my eyes glazed over a ways into that shell dump.

I asked on Twitter. So far only one suggestion: It was the link above https://pypi.org/project/Pygments/ and they said pip3 not pip.

greghendershott commented 5 years ago

Juggling a lot right now, so overlooked something even more basic. The second part of the status quo instructions:

If that fails, try again after installing `easy_install`:

    $ sudo apt-get install python-setuptools

Of course assumes Linux. Won't work on macOS or Windows.

greghendershott commented 5 years ago

Reading Requirements for Installing Packages, it seems like there are enough permutations here that we should link to this.

For example, on macOS it seems like it's just not going to work anymore with the OS-provided Python 2.7 -- except maybe jumping through the hoops you did @jbshirk. Instead, the better experience seems like it would be brew install python, and it's Python 3.x, and that will also include pip, and presumably clean sailing from there. I think??

And for Linux or Windows, whatever needs to be done, presumably will best be described there. Trying to give a 1-2-3 simple version in the Frog Quick Start is, sadly, probably not possible.

@jbshirk You said you heard advice that pip is bad. I'm open to alternatives, but, at the moment the above is my least-worst idea.

p.s. My current laptop is about 2 years old and on macOS 10.11.6. When I installed Pygments 2 years ago, the easy_install approach still worked. IIRC easy_install was already in /usr/bin? The Frog docs and their mention of apt-get date from about a year earlier, when I was using Ubuntu via crouton on a Chromebook.

jab commented 5 years ago

Pip is the right thing to document for installing Python packages. Python 3 (as distributed from python.org) comes with pip as of several years ago. So for the purposes of documentation that is aimed at people who don't have Python familiarity nor necessarily a modern version of Python, the simplest thing to recommend might be to install the latest version of Python from python.org (currently 3.7.0). Then it's just a matter of running python3 -m pip install pygments.

Hopefully that provides a good, simple baseline recommendation that avoids having to account for whatever old or incomplete versions of Python that shipped with whatever OS the user is currently running.

jbshirk commented 5 years ago

@greghendershott

You said you heard advice that pip is bad. I'm open to alternatives, but, at the moment the above is my least-worst idea.

Least worst is still best at the moment. I didn't mind trying to iron out my pythons (I never use it, except for cases like this). I just don't want people to give up on Frog/Pollen because of that... I love what I think I'll be able to do with it!

p.s. My current laptop is about 2 years old and on macOS 10.11.6. When I installed Pygments 2 years ago, the easy_install approach still worked.

You're in better shape than I am. My MBP is 2011 with OSX 10.12.6, which is pushing it with a constantly filling-up 256GB SSD. And you can't offload Developer Tools to an external drive! Two weeks ago my GPU melted down; it took me a week to figure out how to disable it and get my screen back. But now almost all my fave browsers blink incessantly, except Safari, a terrible browser. I'm putting all my hopes on Frog/Pollen to get back on top again and buy a new Mac. Did I mention I love Frog??

greghendershott commented 5 years ago

I'm away from real keyboard for awhile but will follow up on this soon. Thanks for the helpful feedback!

greghendershott commented 5 years ago

I updated the instructions. The hosted docs won't update until the pkg build server does its daily thing.

Thanks again @jbshirk for pointing this out, and @jab for the answer!