mkdocs / catalog

:trophy: :books: A list of awesome MkDocs projects and plugins.
Creative Commons Attribution Share Alike 4.0 International
1.01k stars 58 forks source link

Remove completely nonfunctional and misleading plugin #244

Closed per1234 closed 1 month ago

per1234 commented 1 month ago

What kind of change does this PR introduce?

Description:

This plugin was added as part of a bulk operation (https://github.com/mkdocs/catalog/commit/f0901f271000dc3d0c47a9ca1e3c1a2e0750f83a), evidently without the least vetting.

The plugin author never made an effort to make the plugin do what it claims to do; adding arbitrary additional external source files to the website:

https://github.com/chikamichi/mkdocs-copy#copy-files-in-your-mkdocs-build

mkdocs-copy is a plugin for MkDocs which allows you to copy verbatim arbitrary files in your build.

They instead simply implementing the copying of the specific file (.htaccess) they needed for their own application:

https://github.com/chikamichi/mkdocs-copy/blob/c7d3306cd85e4b0119e8a21cf1c47f972b220fc1/mkdocs_copy/__init__.py#L42-L47

source_file = os.path.join(source_dir, '.htaccess')
exists_dest_file = os.path.isfile(source_file)
logging.debug('source file: ' + source_file +
              ' (exists: ' + str(exists_dest_file) + ')')

exists_dest_file and utils.copy_file(source_file, dest_dir)

The plugin author is aware of this deficiency and tracking it in a vaguely worded issue report in the repository (https://github.com/chikamichi/mkdocs-copy/issues/1), but that issue has been open for over 2.5 years without any effort to actually implement the promised functionality.

The description in the catalog and in the plugin documentation claim the plugin provides the arbitrary file copying capability, and don't make any mention that it doesn't actually do that. Worse, the demonstration MkDocs configuration file snippet in the plugin's documentation appears to configure the plugin to copy a .htaccess file, which would lead the reader who followed the demo as written when evaluating the plugin to think it provided the promised arbitrary file copying functionality until such time as they tried to use the plugin in their own application. The only way they could discover why it stopped working would be to study the plugin's source code or find and correctly interpret the vague issue report in the GitHub repository.

So clearly the plugin is objectively not qualified for inclusion in the catalog and must be removed out of respect for the catalog users.

Checklist:

pawamoy commented 1 month ago

Thank you so much for the investigation, and sorry for the troubles!

evidently without the least vetting.

I did my best with limited time available :)

LGTM, let's merge, thanks again :)