Update sphinx theme (prompt-toolkit#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

Author: danirus

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

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:

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

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",
 ]

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.