Docs: Update from the old default theme to furo.

.readthedocs.yml

@@ -7,11 +7,20 @@ version: 2
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
+  builder: html
   configuration: docs/conf.py
 
-# Optionally set the version of Python and requirements required to build your docs
+
+# Set the version of Python and requirements required to build your
+# docs
+
+build:
+  # os is required for some reason
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 python:
-  version: 3
   install:
     - method: pip
       path: .

docs/_static/custom.css

@@ -0,0 +1,99 @@
+/* Font definitions */
+@font-face {
+  font-family: 'JetBrains Mono';
+  src: url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff2/JetBrainsMono-Bold-Italic.woff2') format('woff2'),
+    url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff/JetBrainsMono-Bold-Italic.woff') format('woff');
+  font-weight: 700;
+  font-style: italic;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'JetBrains Mono';
+  src: url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff2/JetBrainsMono-Bold.woff2') format('woff2'),
+    url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff/JetBrainsMono-Bold.woff') format('woff');
+  font-weight: 700;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'JetBrains Mono';
+  src: url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff2/JetBrainsMono-ExtraBold-Italic.woff2') format('woff2'),
+    url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff/JetBrainsMono-ExtraBold-Italic.woff') format('woff');
+  font-weight: 800;
+  font-style: italic;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'JetBrains Mono';
+  src: url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff2/JetBrainsMono-ExtraBold.woff2') format('woff2'),
+    url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff/JetBrainsMono-ExtraBold.woff') format('woff');
+  font-weight: 800;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'JetBrains Mono';
+  src: url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff2/JetBrainsMono-Italic.woff2') format('woff2'),
+    url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff/JetBrainsMono-Italic.woff') format('woff');
+  font-weight: 400;
+  font-style: italic;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'JetBrains Mono';
+  src: url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff2/JetBrainsMono-Medium-Italic.woff2') format('woff2'),
+    url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff/JetBrainsMono-Medium-Italic.woff') format('woff');
+  font-weight: 500;
+  font-style: italic;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'JetBrains Mono';
+  src: url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff2/JetBrainsMono-Medium.woff2') format('woff2'),
+    url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff/JetBrainsMono-Medium.woff') format('woff');
+  font-weight: 500;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'JetBrains Mono';
+  src: url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff2/JetBrainsMono-Regular.woff2') format('woff2'),
+    url('https://cdn.jsdelivr.net/gh/JetBrains/JetBrainsMono/web/woff/JetBrainsMono-Regular.woff') format('woff');
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+
+
+article {
+/* Furo theme makes this 1.5 which uses soo much space */
+    line-height: 1.1;
+}
+
+a {
+    text-decoration: none;
+}
+
+.admonition-opinion p.admonition-title {
+    background-color: rgba(255, 150, 235, 0.44);
+}
+
+div.admonition-opinion.admonition {
+    border-left: .2rem solid rgba(255, 150, 235, 0.44);
+}
+
+
+.admonition-design-options p.admonition-title {
+    background-color: rgba(173, 28, 237, 0.44);
+}
+
+div.admonition-design-options.admonition {
+    border-left: .2rem solid rgba(173, 28, 237, 0.44);
+}

docs/api.rst

@@ -55,29 +55,16 @@ Greenlets
       for suspended greenlets; it is None if the greenlet is dead, not
       yet started, or currently executing.
 
-      .. warning:: Greenlet stack introspection is fragile on CPython 3.12
+      .. note:: Greenlet stack introspection is fragile on CPython 3.12
          and later. The frame objects of a suspended greenlet are not safe
          to access as-is, but must be adjusted by the greenlet package in
          order to make traversing ``f_back`` links not crash the interpreter,
-         and restored to their original state when resuming the greenlet.
-         This is all handled transparently as long as you obtain references
-         to greenlet frames only via the ``gr_frame`` attribute and you finish
-         accessing them before the greenlet next resumes. If you obtain
-         frames in other ways, or hold onto them across their greenlet's
-         resumption, you must set the ``gr_frames_always_exposed`` attribute
-         in order to make that safe.
-
-   .. autoattribute:: gr_frames_always_exposed
-
-      Writable boolean indicating whether this greenlet will take extra action,
-      each time it is suspended, to ensure that its frame objects are always
-      safe to access. Normally such action is only taken when an access
-      to the ``gr_frame`` attribute occurs, which means you can only safely
-      walk a greenlet's stack in between accessing ``gr_frame`` and resuming
-      the greenlet. This is relevant only on CPython 3.12 and later; earlier
-      versions still permit writing the attribute, but because their frame
-      objects are safe to access regardless, such writes have no effect and
-      the attribute always reads as true.
+         and restored to their original state when resuming the
+         greenlet. The intent is to handle this transparently, but it
+         does introduce additional overhead to switching greenlets,
+         and there may be obscure usage patterns that can still crash
+         the interpreter; if you find one of these, please report it
+         to the maintainer.
 
    .. autoattribute:: parent
 

docs/conf.py

@@ -17,9 +17,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
-import pkg_resources
+from importlib import metadata
 sys.path.append(os.path.abspath('../src/'))
-rqmt = pkg_resources.require('greenlet')[0]
+
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -58,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '%s.%s' % tuple(rqmt.version.split('.')[:2])
+version = metadata.version('greenlet')
 # The full version, including alpha/beta/rc tags.
-release = rqmt.version
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -101,7 +101,23 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+
+html_theme = "furo"
+html_css_files = [
+    'custom.css',
+]
+
+html_theme_options = {
+    "sidebar_hide_name": True, # Because we show a logo
+
+    'light_css_variables': {
+        "color-brand-primary": "#7c9a5e",
+        "color-brand-content": "#7c9a5e",
+        "color-foreground-border": "#b7d897",
+        'font-stack': '"SF Pro",-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"',
+        'font-stack--monospace': '"JetBrainsMono", "JetBrains Mono", "JetBrains Mono Regular", "JetBrainsMono-Regular", ui-monospace, profont, monospace',
+    },
+}
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -130,7 +146,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []  # ['_static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -252,8 +268,9 @@
 #texinfo_show_urls = 'footnote'
 
 intersphinx_mapping = {
-    'https://docs.python.org/': None,
-    'https://www.gevent.org/': None,
+    'python': ('https://docs.python.org/', None),
+    'gevent': ('https://www.gevent.org/', None),
+
 }
 
 
@@ -266,7 +283,7 @@
     #'members': None,
     'show-inheritance': None,
 }
-autodoc_member_order = 'bysource'
+autodoc_member_order = 'groupwise'
 autoclass_content = 'both'
 
 extlinks = {