feat: ci, run on env, linter, move to poetry, chore, docs

[DariuszPorowski]

• added feature to control plugin on/off enabled / enabled_on_serve
  • useful on CI
• added feature to control default set file_types_override_mode: append, remove, replace
  • replace is default to keep backward compatibility
• added path.exists for check -> solve issue on py3.8 and py3.9 on windows
• added common python linters configuration + validation via pre-commit
• moved out from setup.py (its deprecated and soon will be not supported) -> migrated to poetry with pyproject.toml
• added some fixtures for basic tests
• added extra entry points for nicer look in mkdocs.yml (old one keeped for backward compatibility)
  • mkdocs_exclude_unused_files
  • mkdocs-exclude-unused-files
  • exclude_unused_files
  • exclude-unused-files <- picked up this one as default, to keep kinda of mkdocs plugins standard
• added 4 workflows for basic linting (based on pre-commit), deps check, CI and publishing (this one req action on your repo to set pypi token inside secrets)
• general linting

[DariuszPorowski]

Hi @JonasDoesThings, I know this PR is a bit big ;) feel free to ask any questions, suggestions, feedback, etc :)

[JonasDoesThings]

Hey, great PR! Thanks for your work & contribution :)

Looks good overall, just a few question-marks on my end. I've added comments in the according places

[JonasDoesThings]

I'm asking myself if enabled_on_serve would be a more "sane" default to prevent accidental leakage of unused assets by users that haven't read this plugin's documentation thoroughly, expecting the plugin to wipe these unused files away.

Open for input

[DariuszPorowski]

IMHO, no, because serve in mkdocs is used only for local development purpose, and locally you do not care about orphaned files - its imported on the final build that goes for publishing.
Checking orphaned files on serve, just extends local development unnecessary. If someone really wanto to do it, then can enable it explicitly - and this is a purpose of enabled_on_serve.

• ... read this plugin's documentation ... actually it's a user problem ;) because its documented opposite to "no info in the docs at all".

[DariuszPorowski]

just added more descriptive explanation to the docs.

[JonasDoesThings]

I appreciate your responses, I will look over it again tomorrow after work, and merge it after trying it out locally :)

[JonasDoesThings]

Sorry for the late reply, life got in it's way. But I have merged it now!
I have moved the CONTRIBUTING.md file to the root of the directory probably to add visibility.

I've seen that the pyproject's version is set to 0.0.0 according to poetry-dynamic-versioning's recommendations. poetry-dynamic-versioning will automatically use the git tag version when building the package, is there anything else I need to keep in mind when doing that before releasing the new version to PyPi?

Cheers!

[DariuszPorowski]

Hi @JonasDoesThings, no issue at all with time/contrib guide :)

• just keep 0.0.0
• make sure you set PYPI_API_TOKEN secret in your repo: https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository
• publish workflow will trigger on any new tag with v*.*.* pattern (basically when you do GitHub release with v*.*.* tag, it creates a tag and kickoff the workflow)
  • it's the basic workflow, you can extend to different trigger, e.g., on release itself and parse tag and do decisions publish yes/no to pypi (handy on more complex scenarios), but for this case trying to keep simple.
• actually pipx inject poetry poetry-plugin-up is not required in the publish workflow - copy-paste issue on my end, but even if exists, does not impact the publishing.
• poetry-dynamic-versioning takes release tag and uses for package build, and pypi publishing.

[JonasDoesThings]

Finally got this off my TODO list and published the new version 😅
I had to throw in a quick fix in this commit

Besides that everything seems fine and working, version 1.2.1 is published on PyPi now :)
I didn't use the new publish pipeline yet, since I want to read more into the security model of the encrypted-secrets before setting it up.

Cheers! 🎉

PS: poetry-dynamic-versioning is a real quality-of-life improvement 😄

[DariuszPorowski]

@JonasDoesThings cool!

For experiments, create clone of the repo, and use https://test.pypi.org/ for testing publish workflow :)

• GH secrets (more details: https://docs.github.com/en/actions/security-guides/encrypted-secrets?tool=webui)
  • In general, te a store for storing secrets in the secure way to use in the workflows
  • You can set secrets on org, repo or environment level
  • Afterall the concept is the same as Azure KeyVault, HashiCorp Vault, AWS Secrets Manager, Google Secrets Manager, 1password, and many more... but in very simplified way just for GH workflows usage

ps
oh yes, do you want more ideas to "forgot" about maintaining something? :D