I noticed too that the second form given in a cmdoption directive cannot be linked to from an option construct.  The workaround looks like this: :option:`--long <-l>`.  This uses a generic Sphinx (or reST) property: When using :role:`text <thing>`, “thing” will be given as argument to the role but “text” will be displayed.  It’s very useful for references for example, if you don’t want title case in the middle of your sentence of if you need to rephrase the title: “Have a look at the :ref:`detailed explanation <config-explanation>`”.

Even if it can be worked around, can you report this Sphinx bug?