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

enhancement: api docs accessibility updates #2946

Merged
merged 1 commit into from
Jun 26, 2024
Merged

enhancement: api docs accessibility updates #2946

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion build/docs/.phpdoc/template/base.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
{ "name": "Submit Feedback", "url": "https://docs-feedback.aws.amazon.com/feedback.jsp?hidden_service_name=AWS%20SDK%20for%20PHP"},
],
"social": [
{ "iconClass": "fab fa-github", "url": "https://github.com/aws/aws-sdk-php"},
{ "accessiblename": "GitHub Link", "iconClass": "fab fa-github", "url": "https://github.com/aws/aws-sdk-php"},
]
}
%}
1 change: 1 addition & 0 deletions build/docs/.phpdoc/template/components/back-to-top.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
<a href="{{ target_path ?: env.currentFileDestination }}#top" class="phpdocumentor-back-to-top" aria-label="Back To Top"><i class="fas fa-chevron-circle-up"></i></a>
9 changes: 9 additions & 0 deletions build/docs/.phpdoc/template/components/header.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<header class="phpdocumentor-header phpdocumentor-section">
{% include 'components/header-title.html.twig' %}
<input class="phpdocumentor-header__menu-button" type="checkbox" id="menu-button" name="menu-button" aria-label="menu button"/>
<label class="phpdocumentor-header__menu-icon" for="menu-button">
<i class="fas fa-bars"></i>
</label>
{{ include('components/search.html.twig') }}
{% include 'components/topnav.html.twig' %}
</header>
1 change: 1 addition & 0 deletions build/docs/.phpdoc/template/components/headerlink.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
<a href="{{ link(on) ~ (at ? ('#' ~ at)) }}" class="headerlink" aria-label="header link"><i class="fas fa-link"></i></a>
15 changes: 15 additions & 0 deletions build/docs/.phpdoc/template/components/menu.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{% if depth == 1 %}
<h3 class="phpdocumentor-sidebar__root-namespace">
<a href="{{ entry.url }}" class="{{ destinationPath|trim('/', 'left') == entry.url ? '-active' }}">{{ entry.title | shortFQSEN }}</a>
</h3>
{% endif %}
{% if entry.children.count > 0 %}
<ul class="phpdocumentor-list">
{% for child in entry.children %}
<li>
<a href="{{ child.url }}" class="{{ destinationPath|trim('/', 'left') == child.url ? '-active' }}">{{ child.title | shortFQSEN }}</a>
{{ toc(child, 'components/menu.html.twig', maxDepth, depth) }}
</li>
{% endfor %}
</ul>
{% endif %}
2 changes: 1 addition & 1 deletion build/docs/.phpdoc/template/components/search-results.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<section data-search-results class="phpdocumentor-search-results phpdocumentor-search-results--hidden">
<section class="phpdocumentor-search-results__dialog">
<header class="phpdocumentor-search-results__header">
<button class="phpdocumentor-search-results__close"><i class="fas fa-times"></i></button>
<button aria-label="search-results-close-button" class="phpdocumentor-search-results__close"><i class="fas fa-times"></i></button>
</header>
<section class="phpdocumentor-search-results__body">
<ul class="phpdocumentor-search-results__entries"></ul>
Expand Down
103 changes: 103 additions & 0 deletions build/docs/.phpdoc/template/components/sidebar.css.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
.phpdocumentor-sidebar {
margin: 0;
overflow: hidden;
max-height: 0;
}

.phpdocumentor .phpdocumentor-sidebar .phpdocumentor-list {
padding: var(--spacing-xs) var(--spacing-md);
list-style: none;
margin: 0;
}

.phpdocumentor .phpdocumentor-sidebar li {
white-space: nowrap;
text-overflow: ellipsis;
overflow: hidden;
padding: 0 0 var(--spacing-xxxs) var(--spacing-md);
}

.phpdocumentor .phpdocumentor-sidebar abbr,
.phpdocumentor .phpdocumentor-sidebar a {
text-decoration: none;
border-bottom: none;
color: var(--text-color);
font-size: var(--text-md);
padding-left: 0;
transition: padding-left .4s ease-out;
}

.phpdocumentor .phpdocumentor-sidebar a:hover,
.phpdocumentor .phpdocumentor-sidebar a.-active {
padding-left: 5px;
font-weight: 600;
}

.phpdocumentor .phpdocumentor-sidebar__category > * {
border-left: 1px solid var(--primary-color-lighten);
}

.phpdocumentor .phpdocumentor-sidebar__category {
margin-bottom: var(--spacing-lg);
}

.phpdocumentor .phpdocumentor-sidebar__category-header {
font-size: var(--text-md);
margin-top: 0;
margin-bottom: var(--spacing-xs);
color: var(--link-color-primary);
font-weight: 600;
border-left: 0;
}

.phpdocumentor .phpdocumentor-sidebar__root-package,
.phpdocumentor .phpdocumentor-sidebar__root-namespace {
font-size: var(--text-md);
margin: 0;
padding-top: var(--spacing-xs);
padding-left: var(--spacing-md);
color: var(--text-color);
font-weight: normal;
}

@media (min-width: {{ breakpoints['md'] }}) {
.phpdocumentor-sidebar {
border-right: var(--sidebar-border-color) solid 1px;
}
}

.phpdocumentor-sidebar__menu-button {
position: absolute;
top: -100%;
left: -100%;
}

.phpdocumentor-sidebar__menu-icon {
font-size: var(--text-md);
font-weight: 600;
background: var(--primary-color-darker);
color: white;
margin: 0 0 var(--spacing-lg);
display: block;
padding: var(--spacing-sm);
text-align: center;
border-radius: 3px;
text-transform: uppercase;
letter-spacing: .15rem;
}

.phpdocumentor-sidebar__menu-button:checked ~ .phpdocumentor-sidebar {
max-height: 100%;
padding-top: var(--spacing-md);
}

@media (min-width: {{ breakpoints['md'] }}) {
.phpdocumentor-sidebar {
overflow: visible;
max-height: 100%;
}

.phpdocumentor-sidebar__menu-icon {
display: none;
}
}
2 changes: 1 addition & 1 deletion build/docs/.phpdoc/template/components/sidebar.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<input class="phpdocumentor-sidebar__menu-button" type="checkbox" id="sidebar-button" name="sidebar-button" />
<input class="phpdocumentor-sidebar__menu-button" type="checkbox" id="sidebar-button" name="sidebar-button" aria-label="sidebar button"/>
<label class="phpdocumentor-sidebar__menu-icon" for="sidebar-button">
Menu
</label>
Expand Down
12 changes: 12 additions & 0 deletions build/docs/.phpdoc/template/components/table-of-contents-entry.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<dt class="phpdocumentor-table-of-contents__entry -{{ type }} -{{ node.visibility }}">
<a href="{{ link(node) }}" aria-label="{{ node.name }}">{{ node is property ? '$' }}{{ node.name }}{{ node is method or node is function ? '()' }}</a>
<span>
{% if node is constant %}&nbsp;= {{ node.value }}{% endif %}
{% if node is enumCase %}{% if node.value %}&nbsp;= {{ node.value }}{% endif %}{% endif %}
{% if node is property %}&nbsp;: {{ node.type ? node.type|route('class:short')|join('|')|raw : 'mixed' }}{% endif %}
{% if node is method or node is function %}&nbsp;: {{ node.response.type|route('class:short')|join('|')|raw }}{% endif %}
</span>
</dt>
{% if node.summary %}
<dd>{{ node.summary }}</dd>
{% endif %}
2 changes: 1 addition & 1 deletion build/docs/.phpdoc/template/components/topnav.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
{% for key,menu in topMenu|default([]) %}
{% for menuitem in menu %}
<li class="phpdocumentor-topnav__menu-item -{{ key }}">
<a href="{{ menuitem.url }}">
<a href="{{ menuitem.url }}" aria-label="{{ menuitem.accessiblename }}">
<span>
{% if menuitem.icon %}
<i class="fab fa-{{ menuitem.icon }}">{{ menuitem.icon }}</i>
Expand Down
37 changes: 29 additions & 8 deletions build/docs/.phpdoc/template/css/base.css.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,35 @@

{% include 'css/variables.css.twig' %}

/* Base Styles
-------------------------------------------------- */
{#@font-face {#}
{# font-family: 'Amazon Ember';#}
{# src: url('/static/AmazonEmber_Rg.ttf') format('truetype');#}
{# font-weight: normal;#}
{# font-style: normal;#}
{#}#}
@font-face {
font-family: 'Glyphicons Halflings';
src: url(../static/glyphicons-halflings-regular.eot);
src: url(../static/glyphicons-halflings-regular.eot?#iefix) format('embedded-opentype'),
url(../static/glyphicons-halflings-regular.woff2) format('woff2'),
url(../static/glyphicons-halflings-regular.woff) format('woff'),
url(../static/glyphicons-halflings-regular.ttf) format('truetype'),
url(../static/glyphicons-halflings-regular.svg#glyphicons_halflingsregular) format('svg');
}

.glyphicon {
position: relative;
top: 1px;
display: inline-block;
font-family: 'Glyphicons Halflings';
font-style: normal;
font-weight: 400;
line-height: 1;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}

.glyphicon-cog:before {
content:"\e019"
}

.glyphicon-link:before {
content:"\e144"
}

body {
background-color: #fff;
Expand Down
15 changes: 8 additions & 7 deletions build/docs/classes/DocsBuilder.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -709,7 +709,7 @@ private function createHtmlForPaginators(HtmlDocument $html, Api $service)
$html->open('dl');
foreach ($paginators as $name => $config) {
$html->open('dt', 'phpdocumentor-table-of-contents__entry');
$attr = ['href' => '#' . strtolower($name)];
$attr = ['href' => '#' . strtolower($name), 'aria-label' => strtolower($name)];
$html->elem('a', $attr, '<strong>' . $name . '</strong>');
$html->close();
}
Expand Down Expand Up @@ -814,10 +814,11 @@ private function createHtmlForOperation(Service $service, $name, Operation $oper
'a',
[
'href' => $service->exceptionLink . '#shape-'
. strtolower($error->getName())
. strtolower($error->getName()),
'aria-label' => strtolower($error->getName())
],
'<strong>' . $error['name'] . ': ' . '</strong>')
->elem('p', 'phpdocumentor-summary', $desc)
->elem('dd', 'phpdocumentor-summary', $desc)
->close();
}
$html->close();
Expand All @@ -832,7 +833,7 @@ private function createHtmlForOperation(Service $service, $name, Operation $oper
$exampleId = $this->exampleSlug($name, $exampleNumber);
$html->open('h5', ['id' => $exampleId]);
$html->elem('span', null, 'Example ' . $exampleNumber . ': ' . $example['title'] ?? '');
$html->elem('a', ['href' => '#' . $exampleId], $html->glyph('link'));
$html->elem('a', ['href' => '#' . $exampleId, 'aria-label' => 'example link'], $html->glyph('link'));
$html->close();
if (isset($example['description'])) {
$html->elem('p', 'phpdocumentor-summary', $example['description']);
Expand Down Expand Up @@ -952,9 +953,9 @@ private function describeParam(AbstractModel $member, $required = false)

$html->open('div', 'param-attributes')->open('dl');
if ($required) {
$html->elem('dt', 'required', '<strong>Required</strong>: <em>Yes</em>');
$html->elem('dt', 'required', '<dd><strong>Required</strong>: <em>Yes</em></dd>');
}
$html->elem('dt', null, '<strong>Type:</strong> ' . "<em>{$typeDesc}</em>");
$html->elem('dt', null, '<dd><strong>Type:</strong> ' . "<em>{$typeDesc}</em></dd>");
$html->close();
$html->close();

Expand Down Expand Up @@ -1044,7 +1045,7 @@ private function memberSlug($name)

private function memberLink($name)
{
return '<a href="#' . $this->memberSlug($name) . '">' . $name . '</a>';
return '<a href="#' . $this->memberSlug($name) . '" aria-label="' . $name . '">' . $name . '</a>';
}

private function updateSitemap()
Expand Down
2 changes: 1 addition & 1 deletion build/docs/classes/HtmlDocument.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ public function section($num, $text, $anchorPrefix = null, $class = null, $label
{
$anchor = $this->slug($anchorPrefix . '-' . $text);
$ariaLabel = empty($label) ? null : 'aria-label="Go to ' . $label . '"';
$link = ' <a ' . $ariaLabel . ' href="#' . $anchor . '" class="anchor-link">' . $this->glyph('link') . '</a>';
$link = ' <a ' . $ariaLabel . ' href="#' . $anchor . '" class="anchor-link"' . ' aria-label="' . $anchor . ' link">' . $this->glyph('link') . '</a>';
$attrs = ['id' => $anchor];
if ($class) {
$attrs['class'] = $class;
Expand Down
Binary file added build/docs/static/glyphicons-halflings-regular.eot
View file
Open in desktop
Binary file not shown.
Loading