Diagnostics

Every case below is reported while building this site, and none of them costs the button: an unreadable option is dropped and the button still renders. The .. noqa: comment above each one keeps the example site's build quiet while still showing the construct — remove one and the warning appears.

A missing argument

With no URL there is no button, so the directive is drawn as an error block quoting its source — what an argument-less .. image:: does too:

.. button-link::

   There is nowhere for this to point.

An unreadable colour

The eleven colour names are a closed set, so a twelfth is reported and the button renders unpainted rather than carrying a class no stylesheet defines:

A colour nobody defined

An unreadable alignment

:align: takes four names. docutils' image :align: also has top, middle and bottom, which this option does not:

An alignment this option does not have

An outline with no colour

sphinx-design adds a colour class only when :color: was written, so :outline: alone draws nothing at all. It is reported rather than left silently invisible:

An outline with no colour to draw it in

An option that belongs on the other button

sphinx-design accepts :ref-type: here only because both of its button directives share one option spec: it selects how a .. button-ref:: resolves its argument, and this directive's argument is a URL. It is refused by name rather than accepted and ignored:

An option for the directive this build does not have

A reference inside the label

A button is itself a link, so a reference role in its label would nest one link inside another. The reference is kept and shown as its text alone:

See the basics page for the plain forms

An option with no value

:tooltip: is the one option here that requires a value, so writing it bare is reported and no tooltip is set:

A tooltip with nothing to show

An unknown option

A misspelled option is reported and dropped, leaving the button intact:

A misspelled option name