Update sphinx theme (#1937)

* Docs: update theme, resolve warnings * Remove sphinx-colorschemed-images (unused) * Ruff changes to docs/conf.py * ruff lint ignore UP031 in examples/* * ruff lint ignore UP031 in src/* * Extend typos ignore to test_buffer.py
prompt-toolkit · Dec 1, 2024 · a2a1230 · a2a1230
1 parent e02b171
commit a2a1230
Show file tree

Hide file tree

Showing 5 changed files with 126 additions and 46 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -25,13 +25,17 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.graphviz", "sphinx_copybutton"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.graphviz",
+    "sphinx_copybutton",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = {".rst": "restructuredtext"}
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -47,10 +51,21 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+# ---------------------------------------------------------------------
+# Versions.
 # The short X.Y version.
 version = "3.0.48"
 # The full version, including alpha/beta/rc tags.
 release = "3.0.48"
+# The URL pattern to match releases to ReadTheDocs URLs.
+docs_fmt_url = "https://python-prompt-toolkit.readthedocs.io/en/{release}/"
+# The list of releases to include in the dropdown.
+releases = [
+    "latest",
+    release,
+    "2.0.9",
+    "1.0.15",
+]
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -82,8 +97,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "pastie"
-pygments_dark_style = "dracula"
+# pygments_style = "pastie"  # Provided as a theme option below.
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -107,38 +121,103 @@
 
 # on_rtd = os.environ.get("READTHEDOCS", None) == "True"
 
-try:
-    import sphinx_nefertiti
-
-    html_theme = "sphinx_nefertiti"
-    html_theme_path = [sphinx_nefertiti.get_html_theme_path()]
-    html_theme_options = {
-        # "style" can take the following values: "blue", "indigo", "purple",
-        # "pink", "red", "orange", "yellow", "green", "tail", and "default".
-        "style": "default",
-        # Fonts are customizable (and are not retrieved online).
-        # https://sphinx-nefertiti.readthedocs.io/en/latest/users-guide/customization/fonts.html
-        # "documentation_font": "Open Sans",
-        # "monospace_font": "Ubuntu Mono",
-        # "monospace_font_size": "1.1rem",
-        "logo": "logo_400px.png",
-        "logo_alt": "python-prompt-toolkit",
-        "logo_width": "36",
-        "logo_height": "36",
-        "repository_url": "https://github.com/prompt-toolkit/python-prompt-toolkit",
-        "repository_name": "python-prompt-toolkit",
-        "footer_links": ",".join(
-            [
-                "Documentation|https://python-prompt-toolkit.readthedocs.io/",
-                "Package|https://pypi.org/project/prompt-toolkit/",
-                "Repository|https://github.com/prompt-toolkit/python-prompt-toolkit",
-                "Issues|https://github.com/prompt-toolkit/python-prompt-toolkit/issues",
-            ]
-        ),
-    }
-
-except ImportError:
-    html_theme = "pyramid"
+html_theme = "sphinx_nefertiti"
+# html_theme_path = [sphinx_nefertiti.get_html_theme_path()]
+html_theme_options = {
+    "documentation_font": "Open Sans",
+    "monospace_font": "Ubuntu Mono",
+    "monospace_font_size": "1.1rem",
+    # "style" can take the following values: "blue", "indigo", "purple",
+    # "pink", "red", "orange", "yellow", "green", "tail", and "default".
+    "style": "blue",
+    "pygments_light_style": "pastie",
+    "pygments_dark_style": "dracula",
+    # Fonts are customizable (and are not retrieved online).
+    # https://sphinx-nefertiti.readthedocs.io/en/latest/users-guide/customization/fonts.html
+    "logo": "logo_400px.png",
+    "logo_alt": "python-prompt-toolkit",
+    "logo_width": "36",
+    "logo_height": "36",
+    "repository_url": "https://github.com/prompt-toolkit/python-prompt-toolkit",
+    "repository_name": "python-prompt-toolkit",
+    "current_version": "latest",
+    "versions": [(item, docs_fmt_url.format(release=item)) for item in releases],
+    "header_links": [
+        {"text": "Getting started", "link": "pages/getting_started"},
+        {
+            "text": "Tutorials",
+            "match": "/tutorials/*",
+            "dropdown": (
+                {"text": "Build an SQLite REPL", "link": "pages/tutorials/repl"},
+            ),
+        },
+        {
+            "text": "Advanced",
+            "link": "pages/advanced_topics/index",
+            "match": "/advanced_topics/*",
+            "dropdown": (
+                {
+                    "text": "More about key bindings",
+                    "link": "pages/advanced_topics/key_bindings",
+                },
+                {
+                    "text": "More about styling",
+                    "link": "pages/advanced_topics/styling",
+                },
+                {
+                    "text": "Filters",
+                    "link": "pages/advanced_topics/filters",
+                },
+                {
+                    "text": "The rendering flow",
+                    "link": "pages/advanced_topics/rendering_flow",
+                },
+                {
+                    "text": "Running on top of the asyncio event loop",
+                    "link": "pages/advanced_topics/asyncio",
+                },
+                {
+                    "text": "Unit testing",
+                    "link": "pages/advanced_topics/unit_testing",
+                },
+                {
+                    "text": "Input hooks",
+                    "link": "pages/advanced_topics/input_hooks",
+                },
+                {
+                    "text": "Architecture",
+                    "link": "pages/advanced_topics/architecture",
+                },
+                {
+                    "text": "The rendering pipeline",
+                    "link": "pages/advanced_topics/rendering_pipeline",
+                },
+            ),
+        },
+        {
+            "text": "Reference",
+            "link": "pages/reference",
+        },
+    ],
+    "footer_links": [
+        {
+            "text": "Documentation",
+            "link": "https://python-prompt-toolkit.readthedocs.io/",
+        },
+        {
+            "text": "Package",
+            "link": "https://pypi.org/project/prompt-toolkit/",
+        },
+        {
+            "text": "Repository",
+            "link": "https://github.com/prompt-toolkit/python-prompt-toolkit",
+        },
+        {
+            "text": "Issues",
+            "link": "https://github.com/prompt-toolkit/python-prompt-toolkit/issues",
+        },
+    ],
+}
 
 
 # Theme options are theme-specific and customize the look and feel of a theme

diff --git a/docs/pages/reference.rst b/docs/pages/reference.rst
@@ -301,9 +301,11 @@ Filters
 
 .. autoclass:: prompt_toolkit.filters.Filter
     :members:
+    :no-index:
 
 .. autoclass:: prompt_toolkit.filters.Condition
     :members:
+    :no-index:
 
 .. automodule:: prompt_toolkit.filters.utils
     :members:
@@ -334,7 +336,7 @@ Eventloop
 
 .. automodule:: prompt_toolkit.eventloop
     :members: run_in_executor_with_context, call_soon_threadsafe,
-        get_traceback_from_context, get_event_loop
+        get_traceback_from_context
 
 .. automodule:: prompt_toolkit.eventloop.inputhook
     :members:

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,5 @@
-Sphinx<7
+Sphinx>=8,<9
 wcwidth<1
 pyperclip<2
-sphinx_copybutton>=0.5.0,<1.0.0
-sphinx-nefertiti>=0.2.1
+sphinx_copybutton>=0.5.2,<1.0.0
+sphinx-nefertiti>=0.6.0
diff --git a/pyproject.toml b/pyproject.toml
@@ -20,9 +20,8 @@ lint.ignore = [
     "E741", # Ambiguous variable name.
 ]
 
-
 [tool.ruff.lint.per-file-ignores]
-"examples/*" = ["T201"]  # Print allowed in examples.
+"examples/*" = ["UP031", "T201"]  # Print allowed in examples.
 "src/prompt_toolkit/application/application.py" = ["T100", "T201", "F821"]  # pdb and print allowed.
 "src/prompt_toolkit/contrib/telnet/server.py" = ["T201"]  # Print allowed.
 "src/prompt_toolkit/key_binding/bindings/named_commands.py" = ["T201"]  # Print allowed.
@@ -31,8 +30,7 @@ lint.ignore = [
 "src/prompt_toolkit/filters/__init__.py" = ["F403", "F405"]  # Possibly undefined due to star import.
 "src/prompt_toolkit/filters/cli.py" = ["F403", "F405"]  # Possibly undefined due to star import.
 "src/prompt_toolkit/shortcuts/progress_bar/formatters.py" = ["UP031"] # %-style formatting.
-"src/*" = ["UP032"]  # f-strings instead of format calls.
-
+"src/*" = ["UP031", "UP032"]  # f-strings instead of format calls.
 
 [tool.ruff.lint.isort]
 known-first-party = ["prompt_toolkit"]
@@ -63,6 +61,7 @@ locale = 'en-us'  # US English.
 
 [tool.typos.files]
 extend-exclude = [
+    "tests/test_buffer.py",
     "tests/test_cli.py",
     "tests/test_regular_languages.py",
 ]
diff --git a/src/prompt_toolkit/application/current.py b/src/prompt_toolkit/application/current.py
@@ -143,8 +143,8 @@ def create_app_session(
     """
     Create a separate AppSession.
 
-    This is useful if there can be multiple individual `AppSession`s going on.
-    Like in the case of an Telnet/SSH server.
+    This is useful if there can be multiple individual ``AppSession``'s going
+    on. Like in the case of a Telnet/SSH server.
     """
     # If no input/output is specified, fall back to the current input/output,
     # if there was one that was set/created for the current session.