Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify the meaning of button in the docs #158

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Clarify the meaning of button in the docs #158

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
75b187f
clarify Buttons section
gabalafou Aug 30, 2023
1afe3fe
note on accessibility
gabalafou Aug 30, 2023
4cae0cf
copy edits and lint
gabalafou Aug 30, 2023
736d225
fix snippets
gabalafou Aug 30, 2023
ee5ecf6
update test snapshots
gabalafou Aug 30, 2023
f2161ad
copy edits
gabalafou Sep 6, 2023
bd2cff2
Merge branch 'main' into clarify-button-links
gabalafou Oct 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 23 additions & 3 deletions docs/badges_buttons.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,29 @@ See [Bootstrap badges](https://getbootstrap.com/docs/5.0/components/badge/) for

## Buttons

Buttons allow users to navigate to external (`button-link`) / internal (`button-ref`) links with a single tap.
Buttons in Sphinx Design are actually links, which:

- Can be styled to look like
[Bootstrap buttons](https://getbootstrap.com/docs/5.0/components/buttons/)
- Can be external (`button-link`) or internal (`button-ref`)

Most of the time, you should create links using the link syntax for the language
you've chosen:

- [Markdown/MyST links and cross-references](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#examples)
- [rST links and cross-references](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks)

Sometimes, though, you may want to call attention to a particular link or set of
links, or set them apart visually from other links on the site.

:::{admonition} Note on accessibility

Despite the name, `button-link` and `button-ref` do **not** convert to
`<button>` tags in HTML. They are output as `<a>` tags and use CSS to achieve
the button look and feel. This has important accessibility implications. For
example, assistive tech will include Sphinx Design "buttons" when asked to
present a list of all the links on the page.
:::

```{button-link} https://example.com
```
Expand Down Expand Up @@ -139,8 +161,6 @@ Use the `click-parent` option to make the button's parent container also clickab

:::

See the [Material Design](https://material.io/components/buttons) and [Bootstrap](https://getbootstrap.com/docs/5.0/components/buttons/) descriptions for further details.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the link to Material Design here because I couldn't actually figure out how it was related to this section. I mean, I understand that Sphinx Design either depends on or takes inspiration from Material Design, but I just couldn't figure out how the information on the page about Material Buttons was supposed to help me use the SD directives, button-link and button-ref, documented here.

I moved the link to Bootstrap buttons up near the top and in a context that I'm hoping makes it seem more like an optional and auxiliary reference than it does here.

I also got feedback from one of my colleagues that these links (which take you to docs about buttons) made it harder to determine from this section of the SD docs if SD buttons were supposed to be buttons or links.


### `button-link` and `button-ref` options

ref-type (`button-ref` only)
Expand Down
13 changes: 13 additions & 0 deletions docs/snippets/myst/button-link.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
(buttons)=
## Buttons

Comment on lines +1 to +3
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Had to add this in order to get the tests to pass, otherwise I would get:

WARNING: 'any' reference target not found: buttons

```{button-link} https://example.com
```

Expand All @@ -19,3 +22,13 @@ Button text
:color: secondary
:expand:
```

```{button-ref} buttons
:color: info
```

```{button-ref} buttons
:color: info

Reference Button Text
```
13 changes: 13 additions & 0 deletions docs/snippets/rst/button-link.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
.. _buttons:

Buttons
.......

Comment on lines +1 to +5
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto for this. Added to make tests pass. Patterned after the card-link snippet

.. button-link:: https://example.com

.. button-link:: https://example.com
Expand All @@ -15,3 +20,11 @@
.. button-link:: https://example.com
:color: secondary
:expand:

.. button-ref:: buttons
:color: info

.. button-ref:: buttons
:color: info

Reference Button Text
50 changes: 31 additions & 19 deletions tests/test_snippets/snippet_post_button-link.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,36 @@
<section ids="heading" names="heading">
<title>
Heading
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
<inline>
Button text
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-outline-primary" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<inline classes="sd-d-grid">
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary" refuri="https://example.com">
<target refid="buttons">
<section dupnames="buttons" ids="buttons id1" names="buttons">
<title>
Buttons
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
<inline>
Button text
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-outline-primary" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<inline classes="sd-d-grid">
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-info" internal="True" refid="buttons">
<inline classes="std std-ref std std-ref">
Buttons
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-info" internal="True" refid="buttons">
<inline classes="std std-ref std std-ref">
Reference Button Text
50 changes: 31 additions & 19 deletions tests/test_snippets/snippet_pre_button-link.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,36 @@
<section ids="heading" names="heading">
<title>
Heading
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
<inline>
Button text
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-outline-primary" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<inline classes="sd-d-grid">
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary" refuri="https://example.com">
<target refid="buttons">
<section dupnames="buttons" ids="buttons id1" names="buttons">
<title>
Buttons
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
<inline>
Button text
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-outline-primary" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<inline classes="sd-d-grid">
<reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary" refuri="https://example.com">
<inline>
https://example.com
<paragraph>
<pending_xref classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-info" refdoc="index" refdomain="" refexplicit="False" reftarget="buttons" reftype="any" refwarn="True">
<inline>
buttons
<paragraph>
<pending_xref classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-info" refdoc="index" refdomain="" refexplicit="True" reftarget="buttons" reftype="any" refwarn="True">
<inline>
Reference Button Text
Loading