add colophon to guidelines page, update style guide for links and acc…

…essibility page

docs/source/contrib/guidelines/guidelines.rst

@@ -37,3 +37,15 @@ Feature Requests
 * Why you think this feature should be added
 * Screenshots (If applicable)
 
+Colophon
+--------
+
+FTC Docs is built with `Sphinx <https://www.sphinx-doc.org/>`__ using a `theme <https://github.com/readthedocs/sphinx_rtd_theme>`__ provided by `Read the Docs <https://readthedocs.org/>`__.
+
+The `Dark theme <https://github.com/FIRST-Tech-Challenge/ftcdocs-helper/tree/main/sphinx_rtd_dark_mode_v2>`__ is provided by the FTC Docs development team.
+
+.. We might wish to state what version of Sphinx we use and other version info.
+   This is also where we could declare what versions of HTML, XML, CSS we target. Perhaps what browsers we target. 
+   (X)HTML, CSS, or usability standards compliance information and links to website validation tests. This used to be a thing, not so much anymore.
+   Perhaps that we are WCAG compliant someday.
+

docs/source/contrib/style_guide/ftc-docs-accessibility-guidelines.rst

@@ -46,8 +46,7 @@ For FTC Docs this should be all content images, plus any user interface images (
 
 - All content images require Alt text. Some pages do not have alt text for images.  For those page switch alt text the text should be reviewed as the alt text for many is not appropriate. For Example, a single word is not a description.
 - FTC Docs needs to provide text alternatives to the theme switch icon. 
-- We need to fix the alt text link to the FTC Logo, it should read "FTC Docs Home" as it is a functional link to take users back to the home page. 
-- We need to fix the Read the Docs icon.
+- We need to fix the alt text link to the FTC Logo which says "logo". It should read "FTC Docs Home" or just "Home" as it is a functional link to take users back to the home page. 
 
 Guideline 1.2 – Time-based Media
 """"""""""""""""""""""""""""""""
@@ -59,7 +58,8 @@ Those videos have Closed Captioning which is good for those persons who cannot h
 
 **FTC Docs To Do**
 
-- We do not have a a Described Video narrator which would would describe the action in our videos for the visually impaired. This is more of a main FIRST Inspires website issue.
+- We do not have a a Described Video narrator which would would describe the action in our videos for the visually impaired. This is more of a main *FIRST* Inspires website issue.
+- The one video linked is the About FTC video. We've added a ARIA note that indicates how to start the video and offers a brief description of the video content. e.g. that students and mentors are talking about FTC (not exactly Described Video, but it does give some indication of the relevant visual content).
 
 Guideline 1.3 – Adaptable
 """""""""""""""""""""""""
@@ -83,7 +83,7 @@ Make it easier for users to see and hear content including separating foreground
 - FTC Docs uses color alone to mark links, it really needs to underline links, and provide for all the link features like Hover and Visited.
 - For FTC Docs we need to review our use of color for both the light and dark themes. 
   Grey text on dark or light backgrounds may not be of sufficient contrast for those person with vision problems.
-  Admonitions like Notes also have this issue.
+  RST "Admonitions" like Notes also have contrast issues due to the colors of the background and text.
 - The footer (as of Dec. 2024) also has a problem with contrast.
 
 Principle 2 – Operable
@@ -97,11 +97,21 @@ Some things like link spacing and how we link to things are under our control.
 
 **FTC Docs To Do**
 
-- The Read the Docs overlay needs to be keyboard accessible.
 - Do not make use of Access Keys, or make them adjustable. FTC Docs sets Next and Previous keys. We have N=next and P=prev accesskey shortcuts that can't be modified and are active when the next previous buttons DO NOT have focus.
 - The footer links are too close together, making them a touch target problem (making it more likely a person would press the wrong link by accident).
 - We do not have a skip-to-main-content link. Or a way to skip or bypass the sidebar nav links.
 - We link to some PDF's without warning the user. We might need to warn/indicate links external to ftc-docs. I have been surprised a few times when links I thought would be an ftcdocs page actually took me to a PDF or to the FIRST Inspires main site.
+- FTC Docs has choosen to open links to external sites in new tabs. This is done with Javascript.
+
+   This does preserve your current location in FTC Docs and may be convienient for sighted users.
+   This is an accessibility issue related to unexpected context switching,
+   and creates a new browser tab that some users might have trouble noticing or closing and the back browser command doesn't work.
+   We mitigate this somewhat by adding an icon that indicates the link is to an external site.
+   That can be styled with CSS and a span is added with has text that is only for screen readers to say "external". 
+   For FTC Docs we also add "link opens in a new tab" to warn screen reader users that the link will open a new tab.
+
+   The Persona Pages are bad for this. There are grid button links that sometimes take you to a ftc-docs page but often take you to another site with no warning.
+   Ideally all Persona pages should link to ftc-docs pages, some of which might be Gateway Pages to the main FIRST site.
 
 Principle 3 – Understandable
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -117,9 +127,8 @@ Make Web pages appear and operate in predictable ways.
 **FTC Docs To Do**
 
 - Some pages (like the old Field Coordinate System page) had acronyms and excess punctuation that screen readers had trouble with. Revising the text to make it more accessible would make it more readable and understandable for all users. See the Plain Language guide.
-- The sidebar is not predicable to an inexperienced user or a visually impaired person. When a link is clicked the sidebar redraws itself and grabs focus. The focus should be on the content of the link destination.
-- FTC Docs should not open external links in new tabs by default. This is an unexpected context switch that a user cannot recover from by just using the back feature of a browser. If we really want an external link to open in a new tab, there should be text like "(opens in a new tab)" in the link text to tell users it will open in a new tab before it is clicked.
-- We also have a weird CAPTCHA that pops up unexpectedly and with a complete context switch. I've noticed it in the search box. There is also a CAPTCHA related to the submit feedback form.
+- The sidebar is not predicable to an inexperienced user or a visually impaired person. When a link is clicked the sidebar redraws itself and grabs focus. I think the focus should be on the content of the link destination.
+- We also have a weird CAPTCHA that pops up unexpectedly and with a complete context switch. I've noticed it in the search box. There is also a CAPTCHA related to the submit feedback form. There may not be much we can do about that except verify it works with screen readers and keyboard only users.
 
 Principle 4 – Robust
 ^^^^^^^^^^^^^^^^^^^^
@@ -131,5 +140,5 @@ This success criterion is primarily for Web authors who develop or script their
 
 **FTC Docs To Do**
 
-- We probably need to change the fake buttons used in the persona grid pages to real buttons.
+- We probably need to change the fake buttons used in the primary grid pages to real buttons.
 

docs/source/contrib/style_guide/style-guide.rst

@@ -250,6 +250,25 @@ When using ``:ref:`` or ``:doc:`` you may customize the displayed text by surrou
 For example ``:ref:`RC Overview <control_hard_compon/rc_components/index:Robot Controller Overview>``` renders to :ref:`RC Overview <control_hard_compon/rc_components/index:Robot Controller Overview>`.
 This is a link to the Robot Controller Overview section of the index in the rc_components folder.
 
+External Links
+^^^^^^^^^^^^^^
+
+Links to other websites and even to the main *FIRST* Inspires site are call *external links*.
+It's possible to create a link by entering the URL in the text https://www.firstinspires.org/resource-library/ftc/game-and-season-info.
+Sphinx will build a link when it encounters a URL. But that is not the preferred approach.
+
+Use descriptive link text rather than just embedding a URL.
+Use the following RST syntax:
+
+.. code:: rest
+
+   `Game and Season Materials <https://www.firstinspires.org/resource-library/ftc/game-and-season-info>`__
+
+Which looks like: `Game and Season Materials <https://www.firstinspires.org/resource-library/ftc/game-and-season-info>`__
+
+FTC Docs has choosen to open links to external sites in new tabs. This is done with Javascript.
+We mitigate this somewhat by adding an icon that indicates the link is to an external site and add screen reader only text.
+
 Links to Files
 ^^^^^^^^^^^^^^
 
@@ -260,7 +279,7 @@ FTC Docs contains quite a few links to PDFs that should be make more accessible.
 The recommended approach to linking to files is to include in the link a warning that the link is actually a file, the file type, and if possible the file size.
 Ideally that information is in text and included in the link text portion of the link so that a screen reader would read that information and let the user decide if they want to follow the link.
 
-Simple example of a link to a PDF.
+Simple example of a link to a PDF. 
 
 RST Code:
 
@@ -281,15 +300,16 @@ Using a button as a link will visually distinguish a file link from a regular li
 
 The following RST example show a sentence that precedes the button to give context.
 Then the button has text that indicates that clicking it will download a PDF, the size of the PDF, and that it will open in a new browser tab.
+Using the *secondary* color will make color the button FTC orange.
 
 .. code:: rest
 
    Use the following button link to download a PDF of the Field Setup Guide from the *FIRST* Website:
    
    .. button-link:: https://ftc-resources.firstinspires.org/file/ftc/game/fieldguide
-      :color: primary
+      :color: secondary
 
-      Download PDF, 4.5 MB, will open in a new tab
+      Download PDF, 4.5 MB
 
 This looks like:
 
@@ -298,9 +318,9 @@ This looks like:
    * - Use the following button link to download a PDF of the Field Setup Guide from the *FIRST* Website:
 
        .. button-link:: https://ftc-resources.firstinspires.org/file/ftc/game/fieldguide
-          :color: primary
+          :color: secondary
 
-          Download PDF, 4.5 MB, will open in a new tab
+          Download PDF, 4.5 MB
 
 The preferred approach when linking to files is to create what is called a gateway page.
 The gateway page would describes the file, perhaps giving a summary of the content. 
@@ -330,39 +350,10 @@ Here's a gateway page example for the Field Setup Guide PDF.
        Use the following button link to download a PDF of the 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
-
-
-External Links
-^^^^^^^^^^^^^^
-
-.. attention:: We need to resolve the issue of opening external links in new tabs. For accessibilty reasons we should not open most links in new tabs. An exception might be links to files.
-
-   Too many of our links look like they should be internal, but actually take you outside of ftc-docs or to a file. Sometimes to the FIRST Inspires main site, but that is still outside ftc-docs. This is an accessibility issue related to unexpected context switching. Use of Gateway Pages in FTC Docs might help. 
-
-   Example: the Persona Pages are bad for this. There are grid button links that sometimes take you to a ftc-docs page but often take you to another site with no warning. All Persona pages should link to ftc-docs pages, some of which might be Gateway Pages to the main FIRST site.
-
-You can refer to external links as follows:
+          :color: secondary
 
-.. code:: rest
+          Download PDF, 4.5 MB
 
-   `Game and Season Materials <https://www.firstinspires.org/resource-library/ftc/game-and-season-info>`__
-
-Which looks like: `Game and Season Materials <https://www.firstinspires.org/resource-library/ftc/game-and-season-info>`__
-
-It's probably better to include the destination of the link in the link text if outside ftc-docs.
-Which could look like: `Game and Season Materials (FIRST website) <https://www.firstinspires.org/resource-library/ftc/game-and-season-info>`__
-
-More commonly an icon is used to indicate external links (usually a square with a little arrow going thru the upper right corner).
-That can be styled with CSS and a span is added with has text that is only for screen readers to say "external".
-See examples here: https://www.torontomu.ca/accessibility/guides-resources/design/links/
-
-.. attention:: FTC Docs uses Javascript to force external links to open in new tabs. We should stop that and instead use CSS to add the external icon and span.
-
-   We might continue to use the Javascript function to force file links to continue to open in a new tab if that's what we want.
-
 Images
 ------