Docs: Python: Add copy button to code blocks #119948

Aaron Carlisle · 2024-03-27T05:50:44+01:00

Aaron Carlisle commented

2024-03-27 05:50:44 +01:00

Uses the sphinx-copybutton to add a copy icon to code block to quickly copy content to the clipboard.

Aaron Carlisle added 1 commit 2024-03-27 05:51:01 +01:00

81cd5e0c08 Docs: Python: Add copy button to code blocks

Uses the sphinx-copybutton to add a copy icon to code block to quickly copy content to the clipboard.

Aaron Carlisle requested review from Campbell Barton 2024-03-27 05:54:06 +01:00

Campbell Barton reviewed 2024-03-27 06:20:56 +01:00

Campbell Barton left a comment

This seems OK but I'm not keen on making it a hard requirement.

This patch adds a function to make it simpler to check if modules import (also used by furo):

diff --git a/doc/python_api/conf.py b/doc/python_api/conf.py
index 02f95930ae2..8587c8d8091 100644
--- a/doc/python_api/conf.py
+++ b/doc/python_api/conf.py
@@ -5,6 +5,17 @@
 import time
 
 
+def has_module(module_name):
+    found = False
+    try:
+        __import__(module_name)
+        found = True
+    except ModuleNotFoundError as ex:
+        if ex.name != module_name:
+            raise ex
+    return found
+
+
 # These are substituted when this file is copied to the build directory.
 BLENDER_VERSION_STRING = "${BLENDER_VERSION_STRING}"
 BLENDER_VERSION_DOTS = "${BLENDER_VERSION_DOTS}"
@@ -27,6 +38,16 @@ else:
 
 extensions = ["sphinx.ext.intersphinx"]
 intersphinx_mapping = {"blender_manual": ("https://docs.blender.org/manual/en/dev/", None)}
+
+
+# Provides copy button next to code-blocks (nice to have but not essential).
+if has_module("sphinx_copybutton"):
+    extensions.append("sphinx_copybutton")
+
+    # Exclude line numbers, prompts, and console text.
+    copybutton_exclude = ".linenos, .gp, .go"
+
+
 project = "Blender %s Python API" % BLENDER_VERSION_STRING
 root_doc = "index"
 copyright = "Blender Authors"
@@ -48,14 +69,8 @@ html_title = "Blender Python API"
 # The fallback to a built-in theme when `furo` is not found.
 html_theme = "default"
 
-try:
-    import furo
+if has_module("furo"):
     html_theme = "furo"
-    del furo
-except ModuleNotFoundError:
-    pass
-
-if html_theme == "furo":
     html_theme_options = {
         "light_css_variables": {
             "color-brand-primary": "#265787",
diff --git a/doc/python_api/requirements.txt b/doc/python_api/requirements.txt
index 70c385b5e74..8bfd02f05f8 100644
--- a/doc/python_api/requirements.txt
+++ b/doc/python_api/requirements.txt
@@ -11,3 +11,6 @@ requests==2.31.0
 # Without this theme, the default theme will be used.
 furo==2024.1.29
 sphinx-basic-ng==1.0.0b2
+
+# Show a copy button (convenience only).
+sphinx-copybutton==0.5.2

This seems OK but I'm not keen on making it a hard requirement. This patch adds a function to make it simpler to check if modules import (also used by `furo`): ``` diff diff --git a/doc/python_api/conf.py b/doc/python_api/conf.py index 02f95930ae2..8587c8d8091 100644 --- a/doc/python_api/conf.py +++ b/doc/python_api/conf.py @@ -5,6 +5,17 @@ import time +def has_module(module_name): + found = False + try: + __import__(module_name) + found = True + except ModuleNotFoundError as ex: + if ex.name != module_name: + raise ex + return found + + # These are substituted when this file is copied to the build directory. BLENDER_VERSION_STRING = "${BLENDER_VERSION_STRING}" BLENDER_VERSION_DOTS = "${BLENDER_VERSION_DOTS}" @@ -27,6 +38,16 @@ else: extensions = ["sphinx.ext.intersphinx"] intersphinx_mapping = {"blender_manual": ("https://docs.blender.org/manual/en/dev/", None)} + + +# Provides copy button next to code-blocks (nice to have but not essential). +if has_module("sphinx_copybutton"): + extensions.append("sphinx_copybutton") + + # Exclude line numbers, prompts, and console text. + copybutton_exclude = ".linenos, .gp, .go" + + project = "Blender %s Python API" % BLENDER_VERSION_STRING root_doc = "index" copyright = "Blender Authors" @@ -48,14 +69,8 @@ html_title = "Blender Python API" # The fallback to a built-in theme when `furo` is not found. html_theme = "default" -try: - import furo +if has_module("furo"): html_theme = "furo" - del furo -except ModuleNotFoundError: - pass - -if html_theme == "furo": html_theme_options = { "light_css_variables": { "color-brand-primary": "#265787", diff --git a/doc/python_api/requirements.txt b/doc/python_api/requirements.txt index 70c385b5e74..8bfd02f05f8 100644 --- a/doc/python_api/requirements.txt +++ b/doc/python_api/requirements.txt @@ -11,3 +11,6 @@ requests==2.31.0 # Without this theme, the default theme will be used. furo==2024.1.29 sphinx-basic-ng==1.0.0b2 + +# Show a copy button (convenience only). +sphinx-copybutton==0.5.2 ```

Aaron Carlisle referenced this issue from a commit

2024-03-30 01:39:47 +01:00

Docs: Python: Add copy button to code blocks

Aaron Carlisle closed this pull request

2024-03-30 01:42:19 +01:00

Aaron Carlisle deleted branch doc-python-copybutton

2024-03-30 01:42:31 +01:00

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

No reviewers

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Docs: Python: Add copy button to code blocks #119948

Pull request closed