Plugins page should be clearer about actual plugin-installation procedure

[n8willis]

• I have searched the issues (including closed ones) and believe that this is not a duplicate.

I believe there is some overlap under the hood here with #3035 (which also deals with things being "left unsaid" that an experienced user doesn't need said), but I do think this is different enough, because it deals with installation not development.

Issue

The documentation is currently not clear about how, specifically, users are intended to install "namespace" plugins.

The docs page at https://docs.getpelican.com/en/latest/plugins.html says:

Starting with version 4.5, Pelican moved to a new plugin structure utilizing namespace packages that can be easily installed via Pip. Plugins supporting this structure will install under the namespace package pelican.plugins and can be automatically discovered by Pelican. To see a list of Pip-installed namespace plugins that are active in your environment, run:

pelican-plugins

That command allows the user to check and see that no plugins are installed, yes. But if you need to install foo-plug ... what exactly you do do is not said. Is it pip install foo-plug ? Is it pip install pelican-plugins.foo? Is it neither, and it gets handled automatically by the stuff mentioned in the following paragraph? That's not clear from this paragraph, and the fact that it's a new structure, etc., doesn't clarify it.

This section immediately below it:

If you leave the PLUGINS setting as default (None), Pelican will automatically discover namespace plugins and register them. If, on the other hand, you specify a PLUGINS setting as a list of plugins, this auto-discovery will be disabled. At that point, only the plugins you specify will be registered, and you must explicitly list any namespace plugins as well.

If you are using the PLUGINS setting, you can specify plugins in two ways. The first method specifies plugins as a list of strings. Namespace plugins can be specified either by their full names (pelican.plugins.myplugin) or by their short names (myplugin):

talks about this automatic-discovery bit. Is that related to installing plugins, or not? Or just to the namespaces/migrated-to-the-new-repo plugins? Is that information all for post-installation usage? There's no example "install" in this section, so this is a missing puzzle piece.

I'm aware that there is a lot of flux going on in the plugin-repo migration, so that may make this odder than normal, but skipping over detail creates a hurdle real early on here. If it was just "you need to find your plugins somewhere and follow the instructions you find in them," that'd be understandable. Believe me, I do enough Python stuff the rest of the week to not find that surprising. But I went and looked at a couple of them, and they don't say either.

The language here about namespacing & automation really makes it clear that there is some intra-Pelican project architecture involved, but this doc page is missing the specifics that a brand-new Pelican user would need to get rolling.

I'm not taking a particular position on what the docs should say, although defining what you mean by "namespace plugin" and showing an example or two (one namespace plugin, one non-namespace plugin) would, I think, clear it up immediately.

And that'd be really helpful to people just getting started, since most of the other pages in the left-hand sidebar, starting with Quickstart, are that detailed — and some of those reference specific plugins.

[avaris]

How you install the namespace plugins is said: via Pip, which is the canonical way to install any package in python.

Is it pip install foo-plug ? Is it pip install pelican-plugins.foo?

That depends on the plugin and the package name they choose. There is no "fixed" answer but typically they are in the form of pelican-pluginname but not required. Plugins should describe how to install, along with any additional dependencies, and how to use them (i.e. any additional settings they require etc). So, their readme is your guide and it pretty much boils down to:

"you need to find your plugins somewhere and follow the instructions you find in them,"

Except it's not really "somewhere". If you go further down that page to Where to find plugins you will find the location to find namespace plugins, i.e. pelican-plugins organization.

But I went and looked at a couple of them, and they don't say either.

Not sure where you looked but I opened a few plugins randomly and they all describe how to install them. If any plugin in that organization is missing instructions, best to file an issue within that plugins repo.

[n8willis]

How you install the namespace plugins is said: via Pip, which is the canonical way to install any package in python.

via Pip is not a command. Just put an actual example command into the doc. As is done two paragraphs later when it discusses the PLUGINS = setting.

That is what needs fixing here.

Except it's not really "somewhere". If you go further down that page

Except you're not quoting it there, you're rephrasing it all. The documents need to be clear here. That's the section that needs fixing.

Notably, for example, your reply actually uses the namespace prefix pelican-pluginname. Nowhere in the rest of the page does that prefix actually appear. Which is why I pointed out "pelican-plugins.foo" in the example.

So, if it's pelican-pluginname people need, then just update the docs to say pip install pelican-pluginname. That would be clear. What is there now is not.

Not sure where you looked but

How about this for starters: https://github.com/pelican-plugins/more-categories ... which is referred to, by name, and linked to in the "Importing and existing site" document.

[avaris]

via Pip is not a command. Just put an actual example command into the doc. As is done two paragraphs later when it discusses the PLUGINS = setting.

That is what needs fixing here.

That's what I'm trying to say. There is no fixed answer there, it depends on the plugin. Best it can say is pip install plugin-package-name. I don't know if that's more descriptive than via Pip, if you think that would be helpful please feel free to expand this section with a PR.

Except it's not really "somewhere". If you go further down that page

Except you're not quoting it there, you're rephrasing it all. The documents need to be clear here. That's the section that needs fixing.

Well, here is the exact quote from that page: "Namespace plugins can be found in the pelican-plugins organization as individual repositories." Not sure what's different from what I said.

Notably, for example, your reply actually uses the namespace prefix pelican-pluginname. Nowhere in the rest of the page does that prefix actually appear. Which is why I pointed out "pelican-plugins.foo" in the example.

So, if it's pelican-pluginname people need, then just update the docs to say pip install pelican-pluginname. That would be clear. What is there now is not.

No, it's doesn't have to be pelican-pluginname. Most plugins I know use that convention but it is not required, maybe I didn't do a good job at explaining. It could easily be named my-awesome-plugin-for-pelican. It depends on the package name that was used on PyPI. Even more, plugin might have non-python requirements that might involve other installation modes. That's why I said it's best to refer plugins readme.

Not sure where you looked but

How about this for starters: https://github.com/pelican-plugins/more-categories ... which is referred to, by name, and linked to in the "Importing and existing site" document.

Fair enough which leads to my suggestion: "If any plugin in that organization is missing instructions, best to file an issue within that plugins repo."

[justinmayer]

The Pelican Plugin CookieCutter Template includes by default how to Pip-install the plugin, but for some reason that was not utilized when the More Categories plugin was migrated to its own repository.

To rectify that, I just added the following commit, which could be used as a model for how to handle this on an individual plugin level: pelican-plugins/more-categories@586effa

I tend to agree with Avaris that I do not see how to improve the main Pelican Plugins documentation to address the issue described here. That said, I am certainly open to any pull requests that enhance clarity in ways in which I may not presently understand.

@n8willis: Does this address your issue? If not, what specifically would you propose?

[justinmayer]

@n8willis: If there's anything further to be done to improve plugin installation clarity, by all means please send a pull request with your proposed enhancements. Cheers!