From 9e73b59eadb68017c25e8fabf0b9dba2eef6f150 Mon Sep 17 00:00:00 2001 From: Jason Madden Date: Thu, 21 Dec 2023 12:51:54 -0600 Subject: [PATCH] Docs: Update from the old default theme to furo. --- .readthedocs.yml | 13 +++++- docs/_static/custom.css | 99 +++++++++++++++++++++++++++++++++++++++++ docs/api.rst | 27 +++-------- docs/conf.py | 35 +++++++++++---- 4 files changed, 143 insertions(+), 31 deletions(-) create mode 100644 docs/_static/custom.css diff --git a/.readthedocs.yml b/.readthedocs.yml index 42c4a89c..bd4d22fa 100644 --- a/.readthedocs.yml +++ b/.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: . diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 00000000..1bc1260e --- /dev/null +++ b/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); +} diff --git a/docs/api.rst b/docs/api.rst index ebb64a95..9159552d 100644 --- a/docs/api.rst +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 99031421..940a62da 100644 --- a/docs/conf.py +++ b/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 = {