podman docs versions out of sync

[ConorSheehan1]

podman machine init doesn't support the --volume flag anymore, but it's still on the latest docs.

Going to the latest version (3.4.4) explicitly shows the correct docs, without the --volume flag.

Looks like the docs are here https://github.com/containers/podman/tree/main/docs, but I figured it'd make more sense to post the issue in this repo since it's related to docs and the podman repo only has 2 categories for issues: bug and feature. This is neither a bug with podman nor a feature request.

I'd guess it's is just a readthedocs/sphinx config issue.

[TomSweeneyRedHat]

@ConorSheehan1 thanks for the problem report. I don't think it's a ReadTheDocs issue after all, but something we might want to be a little more clear on or perhaps change our man page updating process. The docs that are shown in the top-level directory for docs.podman.io are all driven from the ones in this directory https://github.com/containers/podman/blob/main/docs/source/markdown and the --volume flag is currently in both places.

In late December 2021, @afbjorklund had this commit which added the --volume option to the podman machine init man page upstream.

So what's happening is that by default, docs.podman.io is showing the absolute bleeding edge man page changes that are made upstream in the GitHub Repo.

Perhaps we should instead be showing the latest release there as the default and then have a separate "upstream" selection that would show the docs direct from Podman's upstream GitHub repo?

@rhatdan @baude WDYT?

[afbjorklund]

podman machine init doesn't support the --volume flag anymore

It is probably the opposite, the features on main are not in releases ?

Maybe there is a matching "latest" CI binary, produced with the docs ?

Could possibly also be good to add the actual version to the pages.

Like 4.0.0-dev (or possibly v3.2.0-rc1-2204-gd62752819, but no)

[afbjorklund]

Perhaps we should instead be showing the latest release there as the default and then have a separate "upstream" selection that would show the docs direct from Podman's upstream GitHub repo?

Probably not ideal, to use "latest" with two different meanings for docs and for releases.

https://docs.podman.io/en/latest/

https://github.com/containers/podman/releases/latest/

But it's a bit weird, since I thought that podman.io was upstream ? Otherwise it seems right.

[afbjorklund]

@TomSweeneyRedHat : For this particular feature, one might want to mention that it doesn't work on Mac with the current QEMU. That is, you have to patch and recompile qemu until sometime in the ballpark of QEMU 7.0 or whenever it lands ?

containers/podman#11454 (comment)

https://gitlab.com/wwcohen/qemu/-/commits/9p-darwin

No changes in podman, but something for the user to be aware of perhaps.There are no volumes by default (unlike Docker), so it only happens when explicitely requested. So not really a bug, but something for the Podman 4.0 release notes perhaps.