diff --git a/docs/source/contrib/guidelines/guidelines.rst b/docs/source/contrib/guidelines/guidelines.rst index 254153ad..57055dce 100644 --- a/docs/source/contrib/guidelines/guidelines.rst +++ b/docs/source/contrib/guidelines/guidelines.rst @@ -4,22 +4,17 @@ Contribution Guidelines Contributors are the lifeblood of the project. We welcome contributions but remind everyone to be a :doc:`Gracious Professional `. -Creating a PR --------------- - -PRs should be made to the `FTC Docs `_ repo on GitHub. Your -title should aim to describe the purpose of your PR in a *concise* manner. For more information on creating a -PR, see -`this `_ - - Creating an Issue ------------------ +Please start by creating an issue to describe the problem or the feature you would like. +This allows for discussion to happen which may resolve the issue at that stage, or perhaps clarify the request and the work to be done. + There are two types of issues: bugs and feature requests. A bug report is an issue that describes a problem with the documentation. A feature request is an issue that describes a new feature that should be added to the documentation. + Before creating either make sure to check for duplicates. If you find a duplicate, comment on the issue and add your -input where possible. If possible we would love to see a PR that fixes the issue. If you are unsure how to fix the issue +input where possible. If possible we would love to see a pull request that fixes the issue. If you are unsure how to fix the issue that is perfectly alright. Bug Reports @@ -37,11 +32,28 @@ Feature Requests * Why you think this feature should be added * Screenshots (If applicable) +Creating a Pull Request +----------------------- + +A Pull Request (PR) is a proposal to merge a set of changes from one branch into another. +In a pull request, collaborators can review and discuss the proposed set of changes before they integrate the changes into the main codebase. +In GitHub, a PR will display the differences between the content in the source branch and the content in the target branch. + +PRs should be made to the `FTC Docs `_ repository on GitHub. Your +title should aim to describe the purpose of your PR in a *concise* manner. For more information on creating a PR, see +`creating a pull request `_ +on GitHub. +We have specific guidance for making changes, start with the :doc:`Change Overview `. + Colophon -------- FTC Docs is built with `Sphinx `__ using a `theme `__ provided by `Read the Docs `__. +Sphinx is a documentation generator. +Sphinx converts reStructuredText files into HTML web pages. +Read the Docs is a documentation hosting platform and provides the base Sphinx theme for FTC Docs. + The `Dark theme `__ is provided by the FTC Docs development team. .. We might wish to state what version of Sphinx we use and other version info. diff --git a/docs/source/contrib/style_guide/ftc-docs-accessibility-guidelines.rst b/docs/source/contrib/style_guide/ftc-docs-accessibility-guidelines.rst index e4bb691b..4d288e19 100644 --- a/docs/source/contrib/style_guide/ftc-docs-accessibility-guidelines.rst +++ b/docs/source/contrib/style_guide/ftc-docs-accessibility-guidelines.rst @@ -1,144 +1,154 @@ FTC Docs Accessibility Guidelines ================================= -The Web Content Accessibility Guidelines (WCAG) are part of a series of web accessibility guidelines published by the Web Accessibility Initiative (WAI) of the World Wide Web Consortium (W3C), the main international standards organization for the Internet. They are a set of recommendations for making Web content more accessible, primarily for people with disabilities—but also for all user agents, including highly limited devices, such as mobile phones. +The Web Content Accessibility Guidelines (WCAG) are part of a series of web accessibility guidelines published by the Web Accessibility Initiative (WAI) of the World Wide Web Consortium (W3C), the main international standards organization for the Internet. They are a set of recommendations for making Web content more accessible, primarily for people with disabilities — but also for all user agents, including highly limited devices, such as mobile phones. +See the `WCAG overview `_ +for more information about the WCAG standard. -As of December 2024, FTC Docs meets some of the WCAG success criteria, but fails at others. -We have good page titles and make use of section headers to organize our content. -We fail at accessible site navigation: we don't have a skip to main content link among other problems. +Our goal to address the WCAG Level A success criteria to remove accessibility barriers. +Then move to meet the level AA criteria to improve that accessibility. +See the `How to Meet WCAG Quick Reference `_ for more information. -.. attention:: I think This will be a long page. It's a rough draft. - The idea is to document from the WCAG perspective what is important and relate that to FTC Docs. - The following sections are just outlines that will get filled in. +.. Note:: + This page attempts to document from the WCAG perspective what is important and relate that to FTC Docs. + This page is primarily for content authors. Accessibility issues due to Sphinx or Read the Docs will be dealt with in GitHub issues. - See ``_ - for an ADA Compliance review (which is primarily a WCAG review). +.. contents:: Contents + :local: + :depth: 3 + :backlinks: none + +Principles +---------- + +The following are WCAG principles that the accessibility guidelines are based on. - See https://docs.google.com/spreadsheets/d/1Z_i5QImEdU5CA1j-hBAnpV2jqXNBhC-Rx-bLb0uJnAM/edit?usp=sharing - for a more detailed WCAG analysis of the 30 level A success criteria. +- **Perceivable** - Information and user interface components must be presentable to users in ways they can perceive. - See https://docs.google.com/document/d/1b4BjhLhSdbSScADhpJgLYIyqK69RHIxxOdXWzczOBUw/edit?usp=sharing - for a proposed plan to address FTC Docs accessibility. +- **Operable** - User interface components and navigation must be operable. -.. See `https://docs.google.com/document/d/1_-seP4lzyWeXwlTSd1wlaon35Zm-YqKZUro3rni0Ap4/edit?usp=sharing`_ +- **Understandable** - Information and the operation of the user interface must be understandable. + +- **Robust** - Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies. -.. contents:: Contents - :local: - :depth: 2 - :backlinks: none Principle 1 – Perceivable ^^^^^^^^^^^^^^^^^^^^^^^^^ Information and user interface components must be presentable to users in ways they can perceive. +For the vision impaired this includes providing text alternative for non-text content like images. +It could include Closed Captioning which is a form of subtitling, a process of displaying text on a television, +video screen, or other visual display to provide additional or interpretive information, where the viewer is given the choice of whether the text is displayed. -FTC Docs mostly consists of web pages with text and images. -It should be feasible to make most FTC Docs content perceivable to most users. +Create content that can be presented in different ways (for example simpler layout) without losing information or structure. + +Make it easier for users to see and hear content including separating foreground from background. + +.. Note:: FTC Docs mostly consists of web pages with text and images. It should be feasible to make most FTC Docs content perceivable to most users. Guideline 1.1 – Text Alternatives """"""""""""""""""""""""""""""""" Provide text alternatives for any non-text content so that it can be changed into other forms people need, such as large print, braille, speech, symbols or simpler language. -For FTC Docs this should be all content images, plus any user interface images (such as the dark-light theme switcher icon). +Success Criterion 1.1.1 Non-text Content - Level A +++++++++++++++++++++++++++++++++++++++++++++++++++ -**FTC Docs To Do** +All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. -- 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 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. +- FTC Docs labels some images with Alt Text, but many images have nothing and some Alt Text labels are not proper descriptions. -Guideline 1.2 – Time-based Media -"""""""""""""""""""""""""""""""" +**FTC Docs To Do** + +- FTC Docs has begun setting or updating Alt Text for images. This will likely be a gradual and ongoing process as time permits. + See :ref:`contrib/style_guide/style-guide:Images` in the Style Guidelines for how to provide text alternatives for images. +- See also :doc:`image-and-figure-details`. -Provide alternatives for time-based media. +Success Criterion 1.3.3 - Sensory Characteristics - Level A ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -FTC Docs (and the *FIRST* Inspires site) make use of videos hosted on YouTube. -Those videos have Closed Captioning which is good for those persons who cannot hear the persons speaking in the videos. +Instructions provided for understanding and operating content do not rely solely on sensory characteristics of components such as shape, color, size, visual location, orientation, or sound. **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. -- 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). +- People who are blind and people who have low vision may not be able to understand instructions if they rely only on a description of the shape and/or location of content. Providing additional information in any instructions other than shape and/or location will allow users to understand the instructions even if they cannot perceive shape and/or location. -Guideline 1.3 – Adaptable -""""""""""""""""""""""""" +Principle 2 – Operable +^^^^^^^^^^^^^^^^^^^^^^ -Create content that can be presented in different ways (for example simpler layout) without losing information or structure. +User interface components and navigation must be operable. -FTC Docs mostly does this already. An example of this is that we have a desktop and mobile version of the web site. -We also publish a PDF version of FTC Docs. +.. Note:: FTC Docs has some operable issues to be resolved in Sphinx or the Read the Docs theme. -**FTC Docs To Do** +Guideline 2.4 – Navigable +""""""""""""""""""""""""" +Provide ways to help users navigate, find content, and determine where they are. -- We have some icons (like the theme switcher) that probably should have a visible text description. Icons alone are not good accessible user interface. +Success Criterion 2.4.4 Link Purpose (In Context) - Level A ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Guideline 1.4 – Distinguishable -""""""""""""""""""""""""""""""" +The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general. -Make it easier for users to see and hear content including separating foreground from background. +- FTC Docs has intentionally chosen to open links to external sites in new tabs. This is done with JavaScript. -**FTC Docs To Do** + This does preserve your current location in FTC Docs and may be convenient for sighted users who can easily close the new tab. + This is an accessibility issue related to unexpected context switching, it also creates a new browser tab that some users might have trouble noticing or closing. + It also prevents the *back* browser command from working. + +- There is a FTC Docs Pull Request to add an external link icon and screen reader text to external links. + + We can mitigate the accessibility problem of creating new browser tabs 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 text that is only for screen readers to say "external". + We also add screen reader only text that says "link opens in a new tab" to warn screen reader users that the link will open a new tab. -- 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. - 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. +**FTC Docs To Do** -Principle 2 – Operable -^^^^^^^^^^^^^^^^^^^^^^ -User interface components and navigation must be operable. +- We link to some files like a PDF without warning the user. PDFs often result in a context switch to a PDF viewer. +- I have been surprised a few times when links I thought would be a FTC Docs page actually took me to a PDF or to *FIRST* Inspires web page. + 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. +- See the :ref:`contrib/style_guide/style-guide:links` section of the Style Guide. + There is information about how to create links in RST content including good link text which helps users decide whether they want to follow the link. -This may be hard to fix in FTC Docs without changing the Sphinx or Read the Docs templates, perhaps even requiring changes to how they work. -Sphinx and Read the Docs are not designed for accessibility. +Guideline 2.5 – Input Modalities +"""""""""""""""""""""""""""""""" -Some things like link spacing and how we link to things are under our control. +Make it easier for users to operate functionality through various inputs beyond keyboard. **FTC Docs To Do** -- 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 chosen 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 convenient 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. +- We might want to enhance functionality for mobile users and other forms of input. + But we need to be careful not to introduce problems. + For example, important content in a tooltip that only shows with mouse hover and is not keyboard accessible or accessible on a mobile device. Principle 3 – Understandable ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Information and the operation of the user interface must be understandable. -Make text content readable and understandable. - -- Insert something about plain language. See https://evolvingweb.com/blog/plain-language-guide-how-write-inclusive-digital-content-2024. +Guideline 3.1 – Readable +"""""""""""""""""""""""" -Make Web pages appear and operate in predictable ways. +Make text content readable and understandable. **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. 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. +- Plain language means communicating in a way that’s clear, straightforward, and easy to understand. It helps audiences “get” what you’re saying immediately. See https://evolvingweb.com/blog/plain-language-guide-how-write-inclusive-digital-content-2024. +- Some FTC Docs pages have 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. +- It's OK to discuss a complex subject, but given the wide audience for FTC Docs content authors should consider perhaps a simplified introduction or summary that builds in complexity and/or add links to background information. Principle 4 – Robust ^^^^^^^^^^^^^^^^^^^^ Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies. -Help users avoid and correct mistakes. -This success criterion is primarily for Web authors who develop or script their own user interface components. For example, standard HTML controls already meet this success criterion when used according to specification. +.. Note:: This success criterion is primarily for Web authors who develop or script their own user interface components. For example, standard HTML controls already meet this success criterion when used according to specification. + + Counter example: use of Sphinx primary grids is a problem because they create ‘fake’ buttons that screen readers have problems with. **FTC Docs To Do** -- We probably need to change the fake buttons used in the primary grid pages to real buttons. +- Content authors may wish to take care not to use Sphinx or Read the Docs feature that result in accessibility problems. + +- They should also review their changes in desktop and mobile views and the generated PDFs of FTC Docs content. diff --git a/docs/source/contrib/style_guide/image-and-figure-details.rst b/docs/source/contrib/style_guide/image-and-figure-details.rst index bed961af..1da416b6 100644 --- a/docs/source/contrib/style_guide/image-and-figure-details.rst +++ b/docs/source/contrib/style_guide/image-and-figure-details.rst @@ -383,7 +383,7 @@ This HTML is from the square field image of the Field Coordinate System page.
A square field with X, Y and Z axes shown
-

The Cascade Effect game field

+

The Cascade Effect game field

In a square field configuration the two Alliances face each other across the field. The field is oriented such that the Red Wall is on the right as seen diff --git a/docs/source/contrib/style_guide/style-guide.rst b/docs/source/contrib/style_guide/style-guide.rst index 76fb2163..e8c491a4 100644 --- a/docs/source/contrib/style_guide/style-guide.rst +++ b/docs/source/contrib/style_guide/style-guide.rst @@ -2,18 +2,15 @@ FTC Docs Style Guide ==================== This guide contains the various reStructuredText (RST) and Sphinx specific guidelines for the FTC Docs project. -reStructuredText is the default plaintext markup language used by Sphinx. -Sphinx is a documentation generator. -Sphinx converts reStructuredText files into HTML web pages. -Read the Docs is a documentation hosting platform and provides the base Sphinx theme for FTC Docs. +reStructuredText is the default plain text markup language used by Sphinx. .. contents:: Contents :local: :depth: 1 :backlinks: none -.. This will be a long page. I think we need in-page links. See guidance here: https://www.nngroup.com/articles/formatting-long-form-content/ - In-page links are also an accessibility improvement (imagine having to listen to this entire long page to find the one section near the end that you wanted). +.. This will be a long page. I think we need in page links. See guidance here: https://www.nngroup.com/articles/formatting-long-form-content/ + In page links are also an accessibility improvement (imagine having to listen to this entire long page to find the one section near the end that you wanted). I'll probably add sub-pages for some things (like detailed image guidance). The goal being that most users should find the style guide sufficient. @@ -59,74 +56,49 @@ Web Content Accessibility Guidelines Web Content Accessibility Guidelines (WCAG) are a set of recommendations for making Web content more accessible, primarily for people with disabilities. -FTC Docs is not completely compliant with WCAG. -Our goal to address the Level A success criteria to remove accessibility barriers. -Then move to meet the level AA criteria to improve that accessibility. -See https://www.w3.org/WAI/WCAG22/quickref/?versions=2.2 - -The `WCAG documents `_ -explain how to make web content more accessible to people with disabilities. -Web 'content' generally refers to the information in a web page or web application, - Please refer to the :doc:`ftc-docs-accessibility-guidelines` section of FTC Docs for how to improve the accessibility of content created for FTC Docs. -The following section provide the WCAG principles that the accessibility guidelines are based on. - -Principle 1 – Perceivable -""""""""""""""""""""""""" - -Information and user interface components must be presentable to users in ways they can perceive. -For the vision impaired this includes providing text alternative for non-text content like images. -It could include Closed captioning which is a form of subtitling, a process of displaying text on a television, -video screen, or other visual display to provide additional or interpretive information, where the viewer is given the choice of whether the text is displayed. - -Create content that can be presented in different ways (for example simpler layout) without losing information or structure. - -Make it easier for users to see and hear content including separating foreground from background. - -Principle 2 – Operable -"""""""""""""""""""""" - -User interface components and navigation must be operable. -Make all functionality available from a keyboard. -Provide users enough time to read and use content. -Do not design content in a way that is known to cause seizures or physical reactions. Example: flashing content. -Provide ways to help users navigate, find content, and determine where they are. - -Make it easier for users to operate functionality through various inputs beyond keyboard. +Plain Language +-------------- -Principle 3 – Understandable -"""""""""""""""""""""""""""" +Plain language means communicating in a way that’s clear, straightforward, and easy to understand. It helps audiences “get” what you’re saying immediately. -Information and the operation of the user interface must be understandable. -Make text content readable and understandable. -Make Web pages appear and operate in predictable ways. +Writing in plain language ensures that users can: -Principle 4 – Robust -"""""""""""""""""""" +- Find the information they need +- Understand what they find +- Use the information to fulfill their needs -Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies. -Help users avoid and correct mistakes. -This success criterion is primarily for Web authors who develop or script their own user interface components. For example, standard HTML controls already meet this success criterion when used according to specification. +This article talks about plain language and contains `tips with examples `_. +These are similar to the tips on `Writing for Web Accessibility `_. +Finally, you can explore the `Federal plain language guidelines `_. reStructuredText Documents -------------------------- -.. should talk about RST documents, directives, and general structure issues. +reStructuredText (RST) is the default plaintext `markup language `_ used by Sphinx. +See the `reStructuredText primer `_ for a short introduction. +There is also a `RST cheatsheet `_ that can be helpful to remind you of the basics. + +The following sections illustrate how to write RST for FTC Docs. They are not a tutorial or reference guide for RST. Example Document ^^^^^^^^^^^^^^^^ +The following example shows how content is mixed with RST markup. +The RST markup indicates titles, paragraphs, code samples, images and document sections. + .. code:: ReST - Title - ===== + Article Title + ============= This is an example article. - This is a paragraph. - + A paragraph is a collection of lines. You can have multiple sentances per line. + + Leave a blank line to start a new paragraph. Here is some code: .. code:: java @@ -157,6 +129,8 @@ Example Document .. note:: If you are having issues editing files with the ``.rst`` extension, the recommended text editor is VS Code with the `reStructuredText `_ extension. + + However, a plain text editor works just fine. Though you would need to generate the HTML to see what the document will look like. Document Filenames ^^^^^^^^^^^^^^^^^^ @@ -171,38 +145,152 @@ Suffix filenames with the ``.rst`` extension. Titles and Headings ------------------- -.. attention:: We should also mention things related to document structure and how we want FTC Docs headings. +Titles and Section Headers are both related, and are treated the exact same way. + +In order to create a new Section, SubSection, SubSubSection, and so on, we just +use a special character that we will define for each level. FTC Docs uses the following: + +.. code:: ReST + + Titles + ====== (Equals) + + Sections + -------- (Dash) + + SubSection + ^^^^^^^^^^ (Carrot) + + SubSubSection + """"""""""""" (Double Quotes) + + SubSubSubSection + ++++++++++++++++ (Plus Sign) + +This is what should be used for different levels of sections. +Please nest the sections in order. For example, use SubSection to add something to a Section (not a SubSubSection). + +.. warning:: Titles, Sections, SubSections, etc. must all be uniquely named within the same document. Text ---- -.. attention:: talk about FTC Docs text, paragraphs, lists, tables, admonitions etc. - This is where we just have guidelines and don't repeat info in the tutorials or reference guide. - Example: we can encourage use of the list style of RST table and avoid the ascii box style of table. - Also talk about plain language: https://evolvingweb.com/blog/plain-language-guide-how-write-inclusive-digital-content-2024 +Use the ASCII character set for English text. For special characters (e.g. Greek symbols) use the `standard character entity sets `_. + +Use ``.. math::`` for standalone equations and ``:math:`` for inline equations. +The ``.. math::`` directive uses Latex markup, see this `LaTeX equation cheat sheet (PDF) `_ for more information. + +The standard text formatting markup is quite simple - use: + +* One Asterisk: \*text\* for emphasis (italics) - like *text* +* Two Asterisks: \*\*text\*\* for strong emphasis (boldface) - like **text** +* Two Backticks: \`\`text\`\` for literals - like ``text`` + +Use literals for filenames, function, and variable names. + +Whitespace +---------- + +Indentation +^^^^^^^^^^^ + +Indentation should *always* match the previous level of indentation *unless* you are creating a new content block. + +Indentation of content directives as new line ``.. toctree::`` should be `3` spaces. + +Blank Lines +^^^^^^^^^^^ + +There should be one blank line separating basic text blocks and section titles. There should be one blank line separating text blocks and content directives. + +Interior Whitespace +^^^^^^^^^^^^^^^^^^^ + +Use one space between sentences. + +Tables +------ + +There are many ways to create tables, FTC Docs prefers the `list `_ +or `CSV `_ style of RST table. +Please avoid the ASCII art form of table. + +.. code:: ReST + + .. csv-table:: Frozen Delights! + :header: "Treat", "Quantity", "Description" + :widths: 15, 10, 30 + + "Albatross", 2.99, "On a stick!" + "Crunchy Frog", 1.49, "If we took the bones out, + it wouldn't be crunchy, now would it?" + "Gannet Ripple", 1.99, "On a stick!" + +Which creates the following: + +.. csv-table:: Frozen Delights! + :header: "Treat", "Quantity", "Description" + :widths: 15, 10, 30 + + "Albatross", 2.99, "On a stick!" + "Crunchy Frog", 1.49, "If we took the bones out, + it wouldn't be crunchy, now would it?" + "Gannet Ripple", 1.99, "On a stick!" + +Admonitions +----------- + +Admonitions are RST directives that provide special formatting to the admonition text. +In FTC docs admonitions have a color heading, followed by a color shaded block with the admonition text. +The list of admonitions is: "attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning". +FTC Docs has lots of "note" and "warning" admonitions. + +In RST an admonition looks like: + +.. code:: ReST + + .. note:: This is a note admonition. + This is the second line of the first paragraph. + + - The note contains all indented body elements + following. + - It includes this bullet list. + +Which results in the following: + +.. note:: This is a note admonition. + This is the second line of the first paragraph. + + - The note contains all indented body elements + following. + - It includes this bullet list. + +Please use admonitions to highlight important information. + +.. tip:: Admonitions should usually should be short. Links ----- Effective link text: -- Avoid link text such as “click here” or "learn more." These call-to-actions do not provide any relevant information to someone using a screen reader. +- Avoid link text such as “click here” or "learn more." These call to actions do not provide any relevant information. - Links should be unique and describe where it takes you. If you have multiple links that look or sound similar (but point to different sections), use different words for each link. - Links to files (e.g. Microsoft Word, PDF, etc.) should also indicate the file type or destination within the link text. -- Avoid linking long URLs. Longer, less intelligible URLs used as link text might be difficult to comprehend with assistive technology. -- Links should be clear and concise. Avoid linking entire sentences or paragraphs. +- Avoid using long URLs as link text. Longer, less intelligible URLs used as link text might be difficult to comprehend with assistive technology. +- Link text should be clear and concise. Avoid linking entire sentences or paragraphs. .. tip:: See this guide on `writing hyperlinks `_ for more information. Internal Links ^^^^^^^^^^^^^^ -Internal Links will be auto-generated based on the ReStructuredText filename and section title. +Internal Links will be automatically generated based on the ReStructuredText filename and section title. For example, here are several ways to link to sections and documents. - Use this format to reference a section of the same document: ```Images`_`` Note the single underscore. This renders to the link `Images`_ which is a section further down in this document. -- Use this format to reference the top-level of a document. You can use relative paths ``:doc:`image-and-figure-details``` renders to :doc:`image-and-figure-details`. Or to use absolute paths, put a forward slash at the beginning of the path ``:doc:`/apriltag/vision_portal/visionportal_webcams/visionportal-webcams``` renders to :doc:`/apriltag/vision_portal/visionportal_webcams/visionportal-webcams`. Note that the link text rendered is the main section title of the target page regardless of the target filename. +- Use this format to reference the top level of a document. You can use relative paths ``:doc:`image-and-figure-details``` renders to :doc:`image-and-figure-details`. Or to use absolute paths, put a forward slash at the beginning of the path ``:doc:`/apriltag/vision_portal/visionportal_webcams/visionportal-webcams``` renders to :doc:`/apriltag/vision_portal/visionportal_webcams/visionportal-webcams`. Note that the link text rendered is the main section title of the target page regardless of the target filename. The general way to reference a section in another document is to add a label in front of the section in that other document. Note the leading underscore and trailing colon that surround the label. The label must be unique across all of FTC Docs. You can also reference a Figure with the label method. @@ -231,7 +319,7 @@ The second ``:ref:`` shows a format that lets you specify the link text, otherwi * - another reference to :ref:`IMU or robot axes ` - This shows custom link text. -When using ``:ref:`` or ``:doc:`` you may customize the displayed text by surrounding the actual link with angle brackets ``<>`` and adding the custom text between the first backtick ````` and the first angle bracket ``<``, leaving a space between the text and bracket. +When using ``:ref:`` or ``:doc:`` you may customize the displayed text by surrounding the actual link with angle brackets ``<>`` and adding the custom text between the first back tick ````` and the first angle bracket ``<``, leaving a space between the text and bracket. For example ``:ref:`RC Overview ``` renders to :ref:`RC Overview `. This is a link to the Robot Controller Overview section of the index in the rc_components folder. @@ -251,7 +339,7 @@ Use the following RST syntax: Which looks like: `Game and Season Materials `_ -FTC Docs has chosen to open links to external sites in new tabs. This is done with Javascript. +FTC Docs has chosen 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 @@ -320,7 +408,7 @@ Here's a gateway page example for the Field Setup Guide PDF. * - The Field Setup Guide has the official instructions for assembling and setting up a *FIRST* Tech Challenge field. Typically there are assembly instructions that build structures that then have setup instructions for placing on the field. - There are also teardown instructions that indicate how to take apart the field for storage or transport. + There are also tear down instructions that indicate how to take apart the field for storage or transport. The guide typically has the following sections: @@ -330,7 +418,7 @@ Here's a gateway page example for the Field Setup Guide PDF. - Step by step instructions for assembling parts and setting them on the field. - Most games have tape lines on the field to mark locations or areas of the game. There are also taped areas outside the field for the Alliances, and sometimes for game areas. - 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. + - Finally, there are tear down 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: @@ -388,23 +476,13 @@ FTC Docs has many diagrams. Some are simple like this one for a control system d .. list-table:: * - .. image:: ../../programming_resources/shared/control_system_intro/images/PointToPointControl.jpg - :alt: Two gamepads are connected to a phone, the phone is connected by WiFi Direct to another phone on the robot. + :alt: Two gamepads are connected to a Rev Driver Hub, which is connected by WiFi to a Rev Control Hub on the robot. :width: 40% :class: no-scaled-link -The alt text reads *Two gamepads are connected to a phone, the phone is connected by WiFi Direct to another phone on the robot.* +The alt text reads *Two gamepads are connected to a Rev Driver Hub, which is connected by WiFi to a Rev Control Hub on the robot.* FTC Docs also has photographs. These also need alt text to describe the image. -This next example is on a page discussing hardware tradeoffs including stiff and flexible printer beds. - -.. list-table:: - - * - .. image:: ../../manufacturing/3d_printing/general_knowledge/hardware_tradeoffs/images/flexiblebeds.png - :alt: An image showing how flexible beds peel off of the bed. - :width: 40% - :class: no-scaled-link - -The alt text reads *An image showing how flexible beds peel off of the bed.* Alt Text Guidelines """"""""""""""""""" @@ -506,7 +584,7 @@ There is a blank line before and after the caption. .. figure:: images/into-the-deep-field.png :alt: A square field with X, Y and Z axes shown. - The Cascade Effect game field + The Into The Deep game field In a square field configuration the two Alliances face each other across the field. The field is oriented such that the Red Wall is on the right as seen @@ -523,7 +601,7 @@ Here's what a complex image looks like (with image reduced in size for this exam :width: 25% :class: no-scaled-link - Into The Deep game field + The Into The Deep game field In a square field configuration the two Alliances face each other across the field. The field is oriented such that the Red Wall is on the right as seen @@ -567,7 +645,7 @@ Our HTML documents have a maximum width of 1000 pixels for desktop browsing so i An exception to image size is images like the control system diagrams in the :ref:`Robot Controller Overview `. -Those diagrams are over 2500 pixels wide and greater than 500kb in size. +Those diagrams are over 2500 pixels wide and greater than 500 KB in size. However, that extra resolution is required to properly view the details of all the components and the connections. If those were reduced in resolution, or too heavily compressed as a jpg, relevant details might be lost or hard to see.