More input on this issue:
'cmdoption' is a directive, while 'option' is inline markup. Therefore I wouldn't say they're completely similar, just meant for different
purposes. Both
a directive and inline markup is useful for describing "official python executable options/flags". Regarding per-module options, I'm not sure special markup is needed at all. So a policy has to be define regarding the correct usage of these directives/markups, and probably documented in Doc/documenting/markup.rst
I've done that now in r82961.
Georg
Georg, Your fix indeed clarifies :option:. However, I think that cmdoption could also be made clearer by re-iterating that it is to refer to Python's own options only, and not to be used for command line options of modules. Eli