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.

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index 9039d15a12ebcc2c7f469daf2ad56752dc0b069f..a98ffc86af87787bec4bf1ca6df2b24519989750 100644 (file)
--- 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 63ca49c7667c4b5a69ce7367d3ef2a9fa57b05e8..23a69219d7fbbb3adc5ba78fabb35b204b282d91 100644 (file)
--- 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']))