Merge pull request #49 from MetaboHUB-MetaToul-FluxoMet/furo-theme

Use furo theme for docs

docs/requirements.txt

@@ -1,5 +1,7 @@
-sphinx-rtd-theme==2.0.0
+furo==2024.7.18
 sphinx-design==0.6.0
+sphinx-new-tab-link==0.5.0
+sphinx-copybutton==0.5.2
 cylc-flow==8.3.0
 metomi-rose==2.3.0
 cylc-sphinx-extensions

docs/source/conf.py

@@ -38,6 +38,8 @@
     "sphinx.ext.extlinks",
     # community extensions
     "sphinx_design",
+    "sphinx_new_tab_link",
+    "sphinx_copybutton",
     # cylc.sphinx_ext extensions (from cylc.sphinx_ext-extensions library)
     "cylc.sphinx_ext.cylc_lang",
     # Custom extensions (in ext/ directory)
@@ -46,7 +48,7 @@
     "exec",
 ]
 
-pygments_style = "dracula"  # 🧛🏻‍♂️
+# pygments_style = "dracula"  # 🧛🏻‍♂️
 
 templates_path = ["_templates"]
 exclude_patterns = []
@@ -96,16 +98,19 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 # html_static_path = ["_static"]
-html_logo = "_static/logo_white.png"
 html_favicon = "_static/favicon.ico"
 html_theme_options = {
-    "logo_only": True,
-    "display_version": False,
-    "style_external_links": True,
+    "sidebar_hide_name": True,
+    "light_logo": "logo_blue.png",
+    "dark_logo": "logo_white.png",
 }
 
+new_tab_link_show_external_link_icon = True
+copybutton_exclude = ".linenos, .gp, .go"
+copybutton_copy_empty_lines = False
+
 
 def setup(app):
     app.config.html_static_path.append("_static")

docs/source/index.rst

@@ -8,6 +8,13 @@ Welcome to RTMet's documentation!
 =================================
 
 .. image:: _static/logo_blue.png
+   :class: only-light
+   :align: center
+   :alt: RTMet Logo
+   :scale: 50
+
+.. image:: _static/logo_white.png
+   :class: only-dark
    :align: center
    :alt: RTMet Logo
    :scale: 50

docs/source/user_guide/workflow_control.rst

@@ -15,36 +15,36 @@ the workflow.
     :figwidth: 80%
     :align: center
 
-    The GUI displaying a workflow using the "tree" view. @CylcDoc,2024
+    :emphasis:`The GUI displaying a workflow using the "tree" view. @CylcDoc,2024`
 
-The GUI is accessible through a web browser, and can be launched by running the ``cylc gui`` command.
-This will open a new tab in your default web browser, displaying the Cylc GUI home page.
+The GUI is accessible through a web browser, and can be launched by running the :command:`cylc gui`
+command. This will open a new tab in your default web browser, displaying the Cylc GUI home page.
 
 It can be deployed with Jupyter Hub to support remote and multi-user access. This is useful when you
 want to access the workflow manager from another computer on the same network. The central server is
-started by the ``cylc hub`` command.
+started by the :command:`cylc hub` command.
 
 .. figure:: /_static/screenshots/cylc-hub-official.png
     :alt: Jupyter Hub authentication page
     :figwidth: 80%
     :align: center
 
-    The Jupyter Hub authentication page in a multi-user setup. @CylcDoc,2024
+    :emphasis:`Jupyter Hub authentication page in a multi-user setup. @CylcDoc,2024`
 
 Cylc TUI
 ========
 
 :doc:`Cylc TUI <cylc:7-to-8/major-changes/ui>` is a terminal-based graphical interface
 that ports most of Cylc UI's features to the terminal. It provides a beginner-friendly interface when
 you're remotely accessing the machine running the workflow, and not exposing a Cylc Hub (JupyterHub)
-instance. It requires no setup, and can be opened by running the ``cylc tui`` command.
+instance. It requires no setup, and can be opened by running the :command:`cylc tui` command.
 
 .. figure:: /_static/screenshots/cylc-tui-preview-official.png
     :alt: Cylc terminal user interface
     :align: center
     :figwidth: 80%
 
-    Tui showing the details of a failed job. @CylcDoc,2024
+    :emphasis:`The TUI showing the details of a failed job. @CylcDoc,2024`
 
 Cylc CLI
 ========