Merge pull request #1278 from gusthoff/topic/infrastructure/sphinx/structure/20250704/furo_theme

Sphinx: migrating to Furo theme

Author: gusthoff

frontend/requirements.txt

@@ -1,5 +1,6 @@
 coverage==7.10.7
 docutils==0.21.2
+furo==2025.9.25
 graphviz==0.21
 ipython==9.5.0
 pdf2image==1.17.0

frontend/requirements_frozen.txt

@@ -8,6 +8,7 @@ coverage==7.10.7
 decorator==5.2.1
 docutils==0.21.2
 executing==2.2.1
+furo==2025.9.25
 graphviz==0.21
 idna==3.10
 imagesize==1.4.1

frontend/sphinx/_templates/footer.html

@@ -104,7 +104,6 @@ def get_file_from_conf_ini(path_to_file):
     'sphinx.ext.graphviz',
     'sphinx.ext.extlinks',
     'widget_extension',
-    'sphinx_rtd_theme',
     'sphinx_reredirects',
     'sphinxcontrib.plantuml',
 ]
@@ -183,6 +182,7 @@ def get_file_from_conf_ini(path_to_file):
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
+pygments_dark_style = "monokai"
 
 # Figures, tables and code-blocks are automatically numbered if they
 # have a caption.
@@ -239,8 +239,7 @@ def get_file_from_conf_ini(path_to_file):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-#html_theme = 'learn_theme'
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'furo'
 
 if 'GEN_LEARN_SITE' in os.environ and os.environ['GEN_LEARN_SITE'] == "yes":
     html_title = "learn.adacore.com"
@@ -252,24 +251,47 @@ def get_file_from_conf_ini(path_to_file):
 
 html_theme_path = ['.'] # make sphinx search for themes in current dir
 
+html_css_files = [
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css",
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/solid.min.css",
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css",
+]
+
 # 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
 # documentation.
 #
 html_theme_options = {
-    'logo_only': True,
-    'flyout_display': 'hidden',
-    'version_selector': False,
-    'prev_next_buttons_location': 'bottom',
-    'style_external_links': False,
-    'vcs_pageview_mode': '',
-#    'style_nav_header_background': 'white',
-    # Toc options
-    'collapse_navigation': False,
-    'sticky_navigation': False,
-    'navigation_depth': 4,
-    'includehidden': True,
-    'titles_only': False
+    # furo options
+    'light_css_variables': {
+        'color-brand-primary': '#fa5000',
+        'color-brand-content': '#fa5000',
+        'color-brand-visited': '#9f1b5e',
+        'color-admonition-background': '#faf1ec',
+        'color-admonition-title': '#fa5000',
+        'color-admonition-title-background': '#fadfd2',
+        'color-admonition-title--note': 'var(--color-admonition-title)',
+        'color-admonition-title-background--note': 'var(--color-admonition-title-background)',
+    },
+    'dark_css_variables': {
+        'color-brand-primary': '#fa5000',
+        'color-brand-content': '#fa5000',
+        'color-brand-visited': '#9f1b5e',
+        'color-admonition-background': '#261d1a',
+        'color-admonition-title': '#fa5000',
+        'color-admonition-title-background': '#502000',
+        'color-admonition-title--note': 'var(--color-admonition-title)',
+        'color-admonition-title-background--note': 'var(--color-admonition-title-background)',
+    },
+    'sidebar_hide_name': True,
+    'navigation_with_keys': True,
+    'top_of_page_buttons': ["view", "edit"],
+    # 'announcement': "",
+    # 'footer_icons': [],
+
+    "source_repository": "https://github.com/AdaCore/learn",
+    "source_branch": "main",
+    "source_directory": "content/",
 }
 
 html_show_sphinx = False
@@ -278,6 +300,9 @@ def get_file_from_conf_ini(path_to_file):
     html_logo = "img/logo.svg"
 else:
     html_logo = "img/logo_sandbox.svg"
+    html_theme_options["announcement"] = \
+        "<p>⚠️ This version of the website contains UNPUBLISHED contents. " \
+        "⚠️</p>"
 
 html_favicon = "img/favicon.ico"
 

frontend/sphinx/_templates/layout.html

@@ -14,24 +14,30 @@
     <div id="{{ w.id }}.settings-bar" class="settings-bar">
         <div class="dropdown-container settingsbar-item">
             <button class="dropdown-btn">
-                <span class="fa fa-cog"></span>
+                <span class="fa-solid fa-gear"></span>
                 Settings
             </button>
             <div class="dropdown-content">
-                <label>
-                    <input id="{{ w.id }}.settings-bar.tab-setting" type="checkbox" class="checkbox tab-setting">
-                    Use tabbed editor view
-                </label>
-                <label>
-                    <input id="{{ w.id }}.settings-bar.theme-setting" type="checkbox" class="checkbox theme-setting">
-                    Use the dark theme
-                </label>
+                <div class="settings-bar-entries">
+                    <div class="settings-bar-entry">
+                        <label>
+                            <input id="{{ w.id }}.settings-bar.tab-setting" type="checkbox" class="checkbox tab-setting">
+                            Use tabbed editor view
+                        </label>
+                    </div>
+                    <div class="settings-bar-entry">
+                        <label>
+                            <input id="{{ w.id }}.settings-bar.theme-setting" type="checkbox" class="checkbox theme-setting">
+                            Use the dark theme
+                        </label>
+                    </div>
+                </div>
             </div>
         </div>
 
         <div class="dropdown-container settingsbar-item">
             <button class="dropdown-btn">
-                <span class="fa fa-cog"></span>
+                <span class="fa-solid fa-gear"></span>
                 Switches
             </button>
             <div id="{{ w.id }}.settings-bar.compiler-switches" class="dropdown-content compiler-switches">
@@ -45,7 +51,7 @@
                       </span>
                       <span class="compiler-switch-help">
                         <button id="{{ w.id }}.settings-bar.compiler-switches-help.{{ sw }}" type="button" title="{{ w.switch_description[sw] }}">
-                          <span class="fa fa-question-circle"></span>
+                        <span class="fa-solid fa-circle-question"></span>
                         </button>
                       </span>
                     </div>
@@ -57,11 +63,11 @@
         </div>
 
         <button id="{{ w.id }}.settings-bar.reset-btn" type="button" class="settingsbar-item reset-btn" title="Reset editor to default state">
-            <span class="fa fa-undo"></span>
+            <span class="fa-solid fa-rotate-left"></span>
             Reset
         </button>
         <button id="{{ w.id }}.settings-bar.download-btn" type="button" class="settingsbar-item download-btn" title="Download source files">
-            <span class="fa fa-download"></span>
+            <span class="fa-solid fa-download"></span>
             Download
         </button>
     </div>