Add font preview, fix giant snake, and start adding missing 3.0 content (#2432)

* Fix oversized snake logo file

* Restore resource font output and add headings

* Add dir iteration abstraction

* Add TOCtree-friendly headings to resource folder instead of table headings

* Add hue-shifted quickfix for font previewing under the Font heading

* Add sorting for folders so we get consistent order on local and remote

* Document and clean up additions

* Remove unused code

* Explain why functions are doing things

* Tag ugly stuff with # pending: post-3.0 cleanup

* Pass the str function as the key for file list sorting

* Remove some cruft in process_resource_directory

* Cover academia / 2.6.X stuff

* Big rework for wording in multiple areas

* Clean up create_resource_listin.py a bit

* More links.rst comments

* github pls

* Remove question marks and redundant phrases from faq

* Rephrase web faq

* Regularize phrasing on faq page.

* Change title and phrasing for packaging section

* Use clearer phrasing for a call to action in the intro paragraph

* Remove redundant logo and unused sprinter embed

* Rephrase to emphasize creativity

* Rephrase Libre paragraph on homepage

* Move items from homepage to improve readability

* Move new doc overview to intro page

* Delete old intro page doc type listing

* Add skill tree ref target

* Delete a bunch of stuff from homepage

* Fix comments and missing ref

* More links

* More homepage changes

* Add big GLES page

* FAQ and install crossrefs

* Add for_academia.rst which may need trimming

* Start filling out community and contributing

* Line spacing

* Clean up table comment

* Fix phrasing per @DragonMoffon's suggestion

* Phrasing tweak per @DragonMoffon's suggestion

* link targ weirdness

* Trailing character

* Fix crossref

* Remove extraneous content and rephrase existing SBC sections

* Remove computer lab sections due to being out of scope for the moment

* Rephrase heading

* Rephrase SBC and other educator content

* Address Dragon's feedback on FAQ

* Add word for legibility

Author: pushfoo

doc/_static/css/custom.css

@@ -223,7 +223,10 @@ table.resource-table td {
 }
 table.resource-table td > img {
     display: inline-block;
+    /* Maximum 20% of the smallest display dimension */
+    max-width: min(20vw, 20vh);
 }
+
 table.colorTable {
     border-width: 1px;
 }

doc/about/faq.rst

@@ -1,29 +1,96 @@
+.. _faq:
 
 Frequently asked questions
 ==========================
 
-Can I copy and adapt example code for my own projects?
-------------------------------------------------------
+.. _faq_education:
+
+Can I use Arcade resources in my own educational materials?
+-----------------------------------------------------------
 
-Of course. You can copy and adapt example code for your own projects for any reason.
-In fact, we encourage you to do so. We want you to learn and be successful.
+.. _gh_license: https://github.com/pythonarcade/arcade/blob/development/license.rst
 
-Can Arcade run on the web?
---------------------------
+Yes! Arcade was originally developed for educational use. In addition to
+a page :ref:`academia`, we have further documentation covering:
 
-Currently Arcade projects cannot easily be build to run on the web.
-It can be possible in the future but will require a lot of work
-in pyglet, the underlying library that Arcade uses.
+
+* The :ref:`permissive_mit` covers the library and documentation
+* The :ref:`CC0 Public Domain Dedication <permissive_almost_all_public>` and similar cover the :ref:`resources`
+
+.. _faq_commercial:
 
 Can I use Arcade in a commercial project?
 -----------------------------------------
 
-Of course. Arcade is released under the MIT License. This means you can use it for free.
-Even adapted versions of Arcade or parts of it can be used in commercial projects.
+:ref:`commercial_games`. There's already one commercially released game using Arcade.
 
-Can I use Arcade resources in my own educational materials?
------------------------------------------------------------
+.. _faq-copying:
+
+Can I copy and adapt example code for my own projects?
+------------------------------------------------------
+
+Of course! We encourage you to do so. That's why the example code is there: we
+want you to learn and be successful. See the :ref:`permissive_mit` section to learn
+more about Arcade's license means (you agree not to claim you wrote the whole thing).
+
+Can Arcade run on...?
+---------------------
+
+Windows, Mac, and Linux
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Yes. Most hardware with an Intel or AMD processor from the last ten years will do fine.
+New :ref:`requirements_mac_mseries` can have some hiccups, but they generally work.
+
+.. _faq-raspi:
+
+Raspberry Pi and Other SBCs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Raspberry Pi is a popular brand of Single Board Computers (SBCs).
+
+The Raspberry Pi 4 and 5 can run Arcade under `Raspberry Pi OS`_,
+and the Raspberry Pi 400 *may* also work. As of October 2024,
+:ref:`All other other Raspberry Pi models are incompatible <sbc_unsupported_raspis>`.
+
+Other SBCs *may* work with Arcade 3.0.0. See the :ref:`sbc_requirements` to learn more.
+
+.. _faq_web:
+
+Web
+^^^
+Not yet. For the moment, the Arcade and `pyglet`_ teams are eagerly
+watching ongoing developments in `WebGPU`_ and its `WASM`_ integrations.
+
+.. _WebGPU: https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API
+.. _WASM: https://developer.mozilla.org/en-US/docs/WebAssembly
+
+.. _faq_mobile:
+
+Mobile
+^^^^^^
+Not in the near future. Supporting mobile requires big changes to both
+Arcade and the `pyglet`_ library we use.
+
+.. _faq_android:
+
+Android
+"""""""
+Android support will take a huge amount of work:
+
+#. `pyglet`_ would need to account for mobile-specific OS behavior
+#. Arcade would need to make changes to account for mobile as well
+#. Not all devices will support the necessary :ref:`OpenGL ES versions <requirements_gles>`.
+
+.. _faq_ios:
+.. _faq_ipad:
+
+iOS and iPad
+""""""""""""
+
+Not in the foreseeable future. They are much trickier than web or Android
+for a number of reasons. For near-future iOS and iPad support, you may want to
+to try `Kivy`_.
+
+.. _Kivy: https://kivy.org
 
-Of course! Arcade was built to support learning.
-You can use its materials however you need—
-whether you stick with the original content or make changes to suit your needs.

doc/about/for_academia.rst

@@ -0,0 +1,166 @@
+.. _academia:
+
+For Educators & Researchers
+===========================
+
+.. _citation template: https://github.com/pythonarcade/arcade#citation
+
+Python Arcade was created by Paul V. Craven while teaching at Simpson College.
+
+In addition to the main Arcade 3.0 documentation you are currently reading, there
+are further resources to help academic users. These include:
+
+* The :ref:`citation template <academia_citations>`
+* A companion :ref:`academia_arcade_book` by Arcade's creator
+* Potential 2.6.X maintenance releases to support curricula using Arcade 2.6
+
+
+.. _academia_citations:
+
+Citation Template
+-----------------
+
+Arcade provides a `citation template`_ in `BibTeX`_ format.
+
+To learn more about using this template, please consult the following:
+
+* the documentation of your reference management tool
+* any style guides you are required to follow
+
+
+.. _academia_version_2v3:
+
+Version Considerations
+----------------------
+Most users will be better off using Arade 3.0.
+
+The main case for continuing to use ``2.6.X`` releases is reliance on teaching
+materials which have not yet been updated, including the :ref:`academia_arcade_book`.
+
+
+.. _academia_arcade_book:
+
+Arcade Book
+^^^^^^^^^^^
+
+The creator of Arcade wrote an `Arcade book`_ which covers Python basics in greater depth
+than the main Arcade documentation.
+
+
+It may be some time until the `Arcade book`_ is updated for Arcade 3.0. Doing so requires a
+separate effort after the 3.0 release due to the the scale and number of changes since
+Arcade 2.6.
+
+
+Similarities to this Documentation
+""""""""""""""""""""""""""""""""""
+
+Both the book and the documentation you are currently reading provide:
+
+* all-ages learning resources
+* gentle introductions to Python and Arcade
+
+
+Differences from this Documentation
+"""""""""""""""""""""""""""""""""""
+
+The book caters more heavily to beginners and educators by providing the following
+in a traditional chapter and curriculum structure:
+
+#. Embedded videos covering concepts and past student projects
+#. Lab exercises to help apply chapter material through practice
+#. Translations in `Swedish / Svenska <book_sv>`_ and `German / Deutsche <book_de>`_
+
+It also offers gentle, beginner-friendly introductions to topics which can intimidate
+even the graduates of college-level computer science programs:
+
+#. Editors and development environments
+#. Industry-standard version control tools
+#. CS topics applicable at college-level and beyond
+
+
+.. _2_6_maintenance:
+
+2.6.X Maintenance?
+------------------
+
+The Arcade team is exploring additional *maintenance-only* releases for 2.6.X.
+
+The goals for these still-hypothetical releases would be:
+
+#. Security updates
+#. Compatibility with newer Python versions
+#. Highly limited bug fixes
+
+Since the Arcade team's focus is on improving Arcade 3.0, no new features will be added
+unless at least one of the following is true:
+
+* It is required for a security or compatibilty improvement
+* The effort required is minimal
+
+
+Raspberry Pi and other SBCs
+---------------------------
+
+For educators, Single-Board Computers (SBCs) such as the Raspberry Pi 4 and 5
+are not always the most cost-effective option.
+
+However, they may be an attractive option when at least one of the following
+applies:
+
+* You have an educational discount
+* You have grant or non-profit funding
+* Surplus hardware isn't an option
+
+
+.. _sbc_rule_of_thumb:
+
+SBC Purchasing Rules of Thumb
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note:: These rules help **non-experts** steer toward Arcade-copatible devices.
+
+          You can find more in-depth descriptions of the required OpenGL ES versions
+          and more under the :ref:`sbc_requirements` heading.
+
+
+ARM64 and AMD64 are Easiest
+"""""""""""""""""""""""""""
+
+The :ref:`known-working Raspberry Pi 4 and 5 <sbc_supported_raspi>` are both ARM64
+devices. If you are considering other boards due to price or availability, stick to
+the following CPU architectures:
+
+* ARM64
+* AMD64 (same as most non-Mac desktop CPUs)
+
+No RISC-based SBC has been verified as compatible. Although some *may* work,
+SBCs based on RISC-V CPUs are likely to lack:
+
+* introductory tutorials
+* beginner-friendly documentation 
+
+
+
+Credit Card Rule
+""""""""""""""""
+
+As of October 2024, all compatible and widely-available SBCs are
+larger than credit cards:
+
+* 3.375 inches by 2.125 inches
+* 85.60 mm by 53.98 mm
+
+If you try to use this rule:
+
+#. Compare to the actual circuit board's size, not the size of the package
+#. Use an old hotel key card, expired credit card, or expired debit card
+
+It's unlikey that an SBC board will have magnets. However, the package
+might include them in motors (in kits) or as part of the box itself.
+Using an old card stops you from accidentally wiping a magnetic strip you need.
+
+Although this errs on the side of caution, it also:
+
+* quickly rules out :ref:`incompatible Raspberry Pi models <sbc_unsupported_raspis>`
+* should apply to other SBCs as well

doc/about/intro.rst

@@ -2,20 +2,30 @@
 Introduction
 ============
 
-Welcome to the official documentation of Arcade.
+.. _intro_learning_resources:
 
 Learning Resources
 ------------------
 
-Arcade offers several resources to help you get started regardless of your
-experience level. People learn in different ways, so we try to offer a variety
-of resources to help you learn.
+Arcade provides documentation for different experience levels and
+learning styles.
 
-* Examples
-* Tutorials
-* API Reference
-* Arcade Book
-* Skill Tree
+Getting Started
+^^^^^^^^^^^^^^^
+
+* The :ref:`skill_tree` is a suggested learning order for beginners
+* The :ref:`main-page-tutorials` are guided introductions to new skills
+* The :ref:`example-code` help tinkerers get started quickly
+* The manual in the left-hand sidebar has overviews of concepts and features
+
+Experienced Developers
+^^^^^^^^^^^^^^^^^^^^^^
+
+For more experienced developers, Arcade provides two forms of
+API documentation:
+
+* The :ref:`arcade-api` follows Arcade's module layout and features
+* The :ref:`quick_index` is a single-page search tool
 
 Community driven
 ----------------