search

jimporter / mike

Manage multiple versions of your MkDocs-powered documentation via Git
BSD 3-Clause "New" or "Revised" License
534 stars 47 forks source link

Support a `--exclude-latest n` flag for `delete` command #74

Closed nejch closed 2 years ago

nejch commented 2 years ago

People who deploy versioned pages from CI might want to automatically prune their old docs. It'd be great if adding a step around deploy time would do this for them, e.g. mike delete --exclude-latest 10 would be similar to --all, but would not prune the highest 10 semver versions.

This would be mostly helpful for those who've implemented a dropdown selector and have many versions deployed as part of CI/CD where it starts to look odd after a while.

I realize this can already be scripted by parsing the json manually but would be great to have it natively supported, either as a separate flag or even perhaps yaml config that is consumed when the --all flag is passed. Would this make sense?

This would be kind of analogous to the jfrog CLI's build-discard if it's any inspiration: https://www.jfrog.com/confluence/display/CLI/CLI+for+JFrog+Artifactory#CLIforJFrogArtifactory-DiscardingOldBuildsfromArtifactory

For example, jfrog rt bdi my-build-name --max-builds=10 would prune all but the 10 latest builds, but it has a few other flags like --max-days, --exclude-builds.

jimporter commented 2 years ago

I think this sort of thing is best left to third-party scripts. There are a lot of different strategies one might use when pruning old versions, and I don't think any particular one of those is widely-applicable enough to be a core mike feature. For example, you may want to prune old patch-level versions, but not old major-level versions.

Generally speaking, most of the subcommands in mike are there to make scripting more-complex behaviors on top of mike (relatively) simple, and I think this is a prime example. mike list -j is there to let tools grab the current version info to manipulate it however they like. For example, I do that in my own projects to adjust the "title" attribute of versions so that the dropdown indicates which version is the latest proper release and which version is the current dev build: https://github.com/jimporter/bfg9000/blob/28a61770e9c491ceecea6ba934ded3865a76f9e8/setup.py#L83-L103.

It probably makes sense to document this philosophy in the README though so that people know what to expect. While I certainly welcome people adding extra features on top of mike (and distributing these features as a package if they're useful), I do want to keep mike as simple as I can while meeting the general goal of being "mkdocs gh-deploy but for multiple versions".

nejch commented 2 years ago

Ok, I understand, thanks for the detailed response! I'll close this for now and a separate package might make sense, as the main motivation initially was to not instruct all our projects with versioned docs to script it themselves but have some simple common config for this.