I'm baffled with the resolution of this bug. Removing the docs doesn't help anybody.
In my experience, argparse.REMAINDER works reasonably well, and apparently I'm not alone; there's >100 packages in Debian that use it:
https://codesearch.debian.net/search?q=%5Cbargparse%5B.%5DRE...
Apparently after 7 years they decided it can't be fixed and updated the docs.