adjust links to improve accessibility

docs/source/_static/css/ftc-rtd.css

@@ -145,3 +145,70 @@ div.ethical-sidebar, div.ethical-footer {
 .sphinx-tab img {
 	margin-bottom: 24px;
 }
+
+/* fix link text in body content for accessibility 
+   exclude .sd-btn which are the buttons on the persona pages*/
+.document a:not(.sd-btn) {
+  color: #0000EE;
+  text-decoration-line: underline;
+  text-decoration-style: solid;
+  text-decoration-color: #0000EE;
+  text-underline-offset: 0.2em;
+}
+.document a:not(.sd-btn):visited  {
+  color: #551A8B;
+  text-decoration-style: dotted;  /* many browsers don't support decorations on visited link */
+  text-decoration-color: #551A8B;
+}
+.document a:not(.sd-btn):focus {
+    outline: 1px solid #0000EE;;
+}
+.document a:not(.sd-btn):hover {  
+  text-decoration-thickness: 0.2em;
+  text-underline-offset: 0.25em;
+}
+.document a:not(.sd-btn):active {  
+  text-decoration-style: wavy;
+}
+/* handle dark mode links */
+html[data-theme='dark'] .document a:not(.sd-btn) { 
+  color: #249ee8;
+  text-decoration-line: underline;
+  text-decoration-style: solid;
+  text-decoration-color: #249ee8;
+  text-underline-offset: 0.2em;
+}
+html[data-theme='dark'] .document a:not(.sd-btn):visited {
+  color: #bb7feF;
+  text-decoration-style: dotted;
+  text-decoration-color: #bb7feF;
+}
+html[data-theme='dark'] .document a:not(.sd-btn):focus {
+    outline: 1px solid #249ee8;
+}
+html[data-theme='dark'] .document a:not(.sd-btn):hover {  
+  text-decoration-thickness: 0.2em;
+  text-underline-offset: 0.25em;
+}
+html[data-theme='dark'] .document a:not(.sd-btn):active {  
+  text-decoration-style: wavy;
+}
+/* Screen Reader - No Select class */
+.sr-only-no-select {
+  user-select: none;
+  -webkit-user-select: none;
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  border: 0;
+}
+.icon-external-link:before { /* This is the fa-external-link icon */
+    font-family: FontAwesome;
+    content: "\f08e";
+    margin-left: .2em;
+    text-decoration-line: none;
+}

docs/source/_static/js/external-links-new-tab.js

@@ -1,4 +1,8 @@
 $(document).ready(function () {
-    $('a.external').attr('target', '_blank');
-    $('a.external').attr('rel', 'noopener');
+    $('a.external').each(function( index, elem ) {
+        var str = $(elem).html();
+        $(elem).html(str + '<i class="icon icon-external-link" aria-hidden="true"></i><span class="sr-only-no-select">&nbsp;(external link opens in a new tab)&nbsp;</span>');
+        $(elem).attr('target', '_blank');
+        $(elem).attr('rel', 'noopener');
+    });
 });

docs/source/_templates/footer.html

@@ -23,19 +23,19 @@
         {%- if hasdoc('copyright') %}
         {%- trans path=pathto('copyright'), copyright=copyright|e %}&#169; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
         {%- else %}
-        &#169; 2023 <i>{%- trans copyright=copyright|e %}{{ copyright }}{% endtrans %}</i>
+        &#169; 2025 <i>{%- trans copyright=copyright|e %}{{ copyright }}{% endtrans %}</i>
         {%- endif %}
         {%- endif %}
       </div>
 
       <div>
-        <a href="https://www.firstinspires.org/about/privacy-policy">Privacy Policy</a>
+        <p><a href="{{ pathto('tos/tos') }}">Terms of Service</a></p>
       </div>
       <div>
-        <a href="{{ pathto('tos/tos') }}">Terms of Service</a>
+        <p><a class="external" href="https://www.firstinspires.org/about/privacy-policy">Privacy Policy</a></p>
       </div>
       <div>
-        <a href="https://www.firstinspires.org/report">Report an Incident</a>
+        <p><a href="https://www.firstinspires.org/report">Report an Incident</a></p>
       </div>
 
       <div>
@@ -67,19 +67,9 @@
       </figure>
     </div>
   </div>
-
+<!--
   <div>
-  {% if show_sphinx %}
-    {%- set sphinx_web = '<a href="https://www.sphinx-doc.org/">Sphinx</a>' %}
-    {%- set readthedocs_web = '<a href="https://readthedocs.org">Read the Docs</a>'  %}
-    {#- Translators: the variable "sphinx_web" is a link to the Sphinx project documentation with the text "Sphinx" #}
-    {%- trans sphinx_web=sphinx_web, readthedocs_web=readthedocs_web %}Built with {{ sphinx_web }} using a{% endtrans %}
-    {#- Translators: "theme" refers to a theme for Sphinx, which alters the appearance of the generated documentation #}
-    <a href="https://github.com/readthedocs/sphinx_rtd_theme">{% trans %}theme{% endtrans %}</a>
-    {#- Translators: this is always used as "provided by Read the Docs", and should not imply Read the Docs is an author of the generated documentation. #}
-    {% trans %}provided by {{ readthedocs_web }}{% endtrans %}.
-  {% endif %}
-
   {%- block extrafooter %} {% endblock %}
   </div>
+  -->
 </footer>

docs/source/game_specific_resources/playing_field_resources/playing_field_resources.rst

@@ -2,7 +2,7 @@ Playing Field Resources
 =======================
 
 .. figure:: images/CenterStageField.png
-   :alt: Arena with four teams in alliances areas. Four robots are on the field along with CENTERSTAGE game elements.
+   :alt: Arena with four teams in alliance areas. Four robots are on the field along with CENTERSTAGE game elements.
 
    Traditional Playing Field, CENTERSTAGE presented by RTX, 2023-2024
 
@@ -36,17 +36,17 @@ The guide typically has the following sections:
 - Most games have AprilTags placed around the field that can be used for robot navigation.
 - Finally, there are teardown instructions that indicate how to take the field down for storage or transport.
 
-Use the following button link to download a PDF of the Field Setup Guide from the *FIRST* Website:
+Use the following button link to download a PDF of the current Field Setup Guide from the *FIRST* Website:
 
 .. button-link:: https://ftc-resources.firstinspires.org/file/ftc/game/fieldguide
    :color: primary
 
-   Download PDF, 4.5 MB, will open in a new tab
+   Download Field Setup Guide PDF, 4.5 MB
 
 .. note:: The Field Setup Guide has instructions for assembling an official game set as purchased from AndyMark.
 
    A purchased game set can be full or partial. A partial game set is less expensive and also suitable for teams who
    want official game elements but don't have room to setup a full field.
 
-The `Game and Season Materials page (FIRST website) <https://ftc-resources.firstinspires.org/files/ftc/game>`_ also contains downloadable PDFs for the AprilTag images that can be printed and placed on the field.
-There is also a do it yourself (DIY) Resources section that include CAD models of the game and scoring elements and DIY field and perimeter build guides.
+The `Game and Season Materials page <https://ftc-resources.firstinspires.org/files/ftc/game>`_ also contains a downloadable PDF for the AprilTag images that can be printed and placed on the field.
+There is a Do It Yourself (DIY) Resources section that includes CAD models of scoring elements and DIY field and perimeter build guides.

docs/source/index.rst

@@ -126,13 +126,13 @@ and :doc:`gracious_professionalism/gp` to see why.
 
 **I am a...**
 
-- :doc:`New Team <persona_pages/rookie_teams/rookie_teams>` - New Teams may not know where to start. This is the way!
+- :doc:`New Team <persona_pages/rookie_teams/rookie_teams>` New Teams may not know where to start. This is the way!
 
-- :doc:`Returning Team <persona_pages/veteran_teams/veteran_teams>` - Returning Teams looking for resources can look here.
+- :doc:`Returning Team <persona_pages/veteran_teams/veteran_teams>` Returning Teams looking for resources can look here.
 
-- :doc:`Coach <persona_pages/coach_admin/coach_admin>` - Coaches looking for help or Team Administrative Resources can look here.
+- :doc:`Coach <persona_pages/coach_admin/coach_admin>` Coaches looking for help or Team Administrative Resources can look here.
 
-- :doc:`Mentor <persona_pages/mentor_tech/mentor_tech>` - Technical Mentors looking for Technical Resources should look here first!
+- :doc:`Mentor <persona_pages/mentor_tech/mentor_tech>` Technical Mentors looking for Technical Resources should look here first!
 
 The main menu contains links to the top level content. The following are quick links organized by topic.
 
@@ -290,7 +290,7 @@ The main menu contains links to the top level content. The following are quick l
                :outline:
                :expand:
 
-               SDK GitHub Repository (external)
+               SDK GitHub Repository
 
          .. div:: col-sm pl-1 pr-1
 
@@ -299,7 +299,7 @@ The main menu contains links to the top level content. The following are quick l
                :outline:
                :expand:
 
-               SDK Releases (external)
+               SDK Releases
 
          .. div:: col-sm pl-1 pr-1
 
@@ -308,7 +308,7 @@ The main menu contains links to the top level content. The following are quick l
                :outline:
                :expand:
 
-               Javadoc Documentation (external)
+               Javadoc Documentation
 
    .. grid-item-card:: 
       :class-header: sd-bg-secondary font-weight-bold sd-text-black
@@ -350,7 +350,7 @@ The main menu contains links to the top level content. The following are quick l
                :outline:
                :expand:
 
-               Game Question and Answer System (external)
+               Game Question and Answer System
 
 .. note::
 

docs/source/overview/ftcoverview.rst

@@ -1,11 +1,32 @@
-About the *FIRST* Tech Challenge
-================================
+.. role:: wordmark
 
-It’s way more than building robots. *FIRST* Tech Challenge teams (up to 15 team
-members, grades 7-12) are challenged to design, build, program, and operate
+.. role:: superscript
+
+.. |FIRST| replace:: :wordmark:`FIRST`
+
+.. |FTC| replace:: :wordmark:`FIRST` Tech Challenge
+
+.. |FIRST-reg| replace:: :wordmark:`FIRST`\ :superscript:`®`
+
+.. |FTC-reg| replace:: :wordmark:`FIRST`\ :superscript:`®` Tech Challenge
+
+.. comment: the roles are converted into CSS Class names that we can target with CSS. 
+   :wordmark: is used to italicize the FIRST word.
+   :superscript: will superscript anything but was intended for Registered and Copyright symbols.
+   Replace all *FIRST* with |FIRST|. this uses CSS instead of <em> to italicize FIRST. This avoids spoken word pauses that surround <em> text.
+   We can also use the substitutions and a role to superscript the Registered symbol.
+   We add a FTC subsitution for future convienience, no need to replaces existing text.
+   We add |FIRST-reg| and |FTC-reg| substitutions which can be used to add the registered mark to the first use of FIRST or FTC in body text as per FIRST branding.
+   Don't use the registered mark in the document heading because the Registered mark will get imbedded in all links including the sidebar and we'd have registered marks everywhere.
+
+About the |FIRST| Tech Challenge
+====================================
+
+It’s way more than building robots. |FTC-reg| teams (up to 15 team
+members, grades 7 to 12) are challenged to design, build, program, and operate
 robots to compete in a head-to-head challenge in an alliance format.
 
-Guided by adult coaches and mentors, students develop STEM skills and practice
+Guided by adult coaches and mentors, students develop :abbr:`STEM (Science, Technology, Engineering, and Mathematics)` skills and practice
 engineering principles, while realizing the value of hard work, innovation, and
 working as a team.
 
@@ -18,55 +39,55 @@ enlistment, and other employment pathways.
 .. comment
    Build the FIRST Championship link so we can italicize FIRST.
 
-Each season concludes with regional championship events and an exciting |text|_.
+Teams compete at regional events leading up to an exciting |text|_ that concludes the season.
 
 .. _text: https://www.firstchampionship.org/
-.. |text| replace:: *FIRST* Championship
-
+.. |text| replace:: |FIRST| Championship
 
 .. only:: latex
 
    `About FIRST Tech Challenge (2021) <https://www.youtube.com/embed/y5NPp_5KHuk>`__
 
 .. raw:: html
 
+   <span class="sr-only-no-select">The following YouTube video has students and mentors talking about the FIRST Tech Challenge. Locate the Play push button to start the video.</span>
    <iframe width="100%" height="452" src="https://www.youtube.com/embed/y5NPp_5KHuk?enablejsapi=1" title="About FIRST Tech Challenge (2021)" frameborder="0" allow="accelerometer; autoplay; clipboard-write; enablejsapi; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
 |
 
-Start a *FIRST* Tech Challenge Team
+Start a |FIRST| Tech Challenge Team
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-*FIRST* Tech Challenge teams design and build a robot using a reusable kit of
+|FTC| teams design and build a robot using a reusable kit of
 parts and compete within a common set of game rules to play an exciting field
 game and complete the specific season challenge. The robot game changes every
 season and is always a blast!
 
 Student and adult team members are encouraged to bring any skills they already
 have, like programming, electronics, metalworking, graphic design, web
-creation, public speaking, videography, and many more. *FIRST* Tech Challenge
+creation, public speaking, videography, and many more. |FIRST| Tech Challenge
 welcomes every student, with or without special skills.
 
-If you are looking to incorporate *FIRST* into your classroom or after-school
-programming, learn more about *FIRST* Class Pack, a flexible implementation
+If you are looking to incorporate |FIRST| into your classroom or after-school
+programming, learn more about |classpack|_, a flexible implementation
 option for up to 24 students.
 
-.. comment
-   Build the Start a Team link so we can italicize FIRST.
+.. _classpack: https://info.firstinspires.org/class-pack/firsttechchallenge
+.. |classpack| replace:: |FIRST| Class Pack
 
-Continue on to learn about the |text2|_
+Visit |text2|_ to learn about the essential steps to starting a team!
 
 .. _text2: https://www.firstinspires.org/robotics/ftc/start-a-team
-.. |text2| replace:: essential steps to starting a *FIRST* Tech Challenge Team!
+.. |text2| replace:: start a |FIRST| Tech Challenge Team
 
-About *FIRST* Tech Challenge Kahoot
+About |FIRST| Tech Challenge Kahoot
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This is a fun self-led *FIRST* Tech Challenge `Kahoot
-<https://create.kahoot.it/course/f79560a1-df68-44dd-bbef-d8c9bf5a27f5>`__ to
-test and build your knowledge. Learn about the many facets of *FIRST* Tech
-Challenge and the Core Values of *FIRST* in the *FIRST* Tech Challenge `Kahoot
-<https://create.kahoot.it/course/f79560a1-df68-44dd-bbef-d8c9bf5a27f5>`__.
+A Kahoot is a self-led learning game to build and test your knowledge.
+|FIRST| has created a series of Kahoots in the areas of |FTC|, robots, game play, events and awards. 
 
+Visit |text3|_ to learn about the many facets of |FIRST| Tech Challenge and |FIRST| Core Values.
 
+.. _text3: https://create.kahoot.it/course/f79560a1-df68-44dd-bbef-d8c9bf5a27f5
+.. |text3| replace:: |FIRST| Tech Challenge Kahoots