search

pelican-plugins / series

Series is a Pelican plugin that joins multiple posts into a series
11 stars 4 forks source link

adding plugin loading to README.md, fixes #29 #30

Closed mpounsett closed 1 year ago

justinmayer commented 1 year ago

Hi Matthew. I appreciate the intention to clarify the usage instructions of this plugin. A few thoughts:

  1. In the future, when there is an intention to submit a pull request, there is no need to submit both an issue and a pull request: the pull request will suffice on its own.
  2. The documentation is actually quite correct as it currently stands, in that the setting you mentioned in your PR is only necessary if you want to explicitly enable plugins. In the absence of that setting, plugins in Pelican 4.5+ are implicitly registered and automatically enabled by default. While this fact is quite adequately explained in the Pelican documentation on plugins, some folks seem to miss that part, so I recently added a new paragraph to the plugin Cookiecutter template that makes this more visible to folks who only read the plugin README and who don’t read the Pelican documentation on plugin behavior.

In short, if there is to be a change to the README, it should be the change referenced in the link above.

justinmayer commented 1 year ago

Closing in favor of 2d6cf2d. For more detail, see: https://github.com/pelican-plugins/series/issues/29#issuecomment-1704307840

mpounsett commented 1 year ago

Hi Matthew. I appreciate the intention to clarify the usage instructions of this plugin. A few thoughts:

  1. In the future, when there is an intention to submit a pull request, there is no need to submit both an issue and a pull request: the pull request will suffice on its own.

Thanks. This is a style choice that's different from project to project, and I didn't see any explicit instructions in the contribution docs, so went with the option that was least likely to be problematic if wrong. :)

  1. The documentation is actually quite correct as it currently stands, in that the setting you mentioned in your PR is only necessary if you want to explicitly enable plugins. In the absence of that setting, plugins in Pelican 4.5+ are implicitly registered and automatically enabled by default. While this fact is quite adequately explained in the Pelican documentation on plugins, some folks seem to miss that part, so I recently added a new paragraph to the plugin Cookiecutter template that makes this more visible to folks who only read the plugin README and who don’t read the Pelican documentation on plugin behavior.

In short, if there is to be a change to the README, it should be the change referenced in the link above.

That's fine, and a completely reasonable approach. Since I have a plugin that requires explicit loading, the absence of those instructions caused a problem that searching for solutions did not solve. It wasn't until I stumbled across the pypi version of the docs, which indicate explicit loading of the plugin is necessary (to be clear, they don't mention auto-loading either, but go the other way from the README and recommend explicit loading) that I had a solution.