From 5094ea8462bdcc61bf9173545cea7aa290fc5ea5 Mon Sep 17 00:00:00 2001
From: Gereon Kremer <nafur42@gmail.com>
Date: Mon, 8 Nov 2021 15:37:10 -0800
Subject: [PATCH] Improve rendering of expert options. (#7589)

The way expert-only options have been rendered in the documentation emphasized those options, which is exactly what should not be done. This PR changes the rendering to make those options slightly opaque instead.
---
 docs/_static/custom.css  |  4 ++++
 src/options/mkoptions.py | 12 ++++++------
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index 9039d15a1..a98ffc86a 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -98,3 +98,7 @@ a:hover, a:focus {
 .hide-toctree {
   display: none;
 }
+
+.expert-option {
+  opacity: 0.7;
+}
\ No newline at end of file
diff --git a/src/options/mkoptions.py b/src/options/mkoptions.py
index 63ca49c76..23a69219d 100644
--- a/src/options/mkoptions.py
+++ b/src/options/mkoptions.py
@@ -760,17 +760,17 @@ def _sphinx_help_render_option(res, opt):
     """Render an option to be displayed with sphinx."""
     indent = ' ' * 4
     desc = '``{}``'
+    if opt['alternate']:
+        desc += ' (also ``--no-*``)'
     val = indent + '{}'
+
     res.append('.. _lbl-option-{}:'.format(opt['long_name']))
     res.append('')
     if opt['expert']:
-        res.append('.. admonition:: This option is intended for Experts only!')
-        res.append(indent)
-        desc = indent + desc
-        val = indent + val
+        res.append('.. rst-class:: expert-option simple')
+        res.append('')
+        desc += '\n{0}.. rst-class:: float-right\n\n{0}**[experts only]**\n'.format(indent)
 
-    if opt['alternate']:
-        desc += ' (also ``--no-*``)'
     res.append(desc.format(' | '.join(opt['name'])))
     res.append(val.format(opt['help']))
 
-- 
2.30.2