From: Kefu Chai <k.chai@proxmox.com>
Date: Tue, 17 Mar 2026 10:33:42 +0000 (+0800)
Subject: doc: show runtime-updatable config metadata
X-Git-Tag: v21.0.0~51^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F67865%2Fhead;p=ceph.git

doc: show runtime-updatable config metadata

Extend the confval Sphinx extension to render whether an option
can be updated at runtime.

Use the same policy as Option::can_update_at_runtime() so the
documentation reflects both native config options and mgr module
options consistently.

Signed-off-by: Kefu Chai <k.chai@proxmox.com>
---

diff --git a/doc/_ext/ceph_confval.py b/doc/_ext/ceph_confval.py
index b997224ce4e..abd3abaee60 100644
--- a/doc/_ext/ceph_confval.py
+++ b/doc/_ext/ceph_confval.py
@@ -31,6 +31,7 @@ TEMPLATE = '''
    {{ desc | wordwrap(70) | indent(3) }}
 {% endif %}
    :type: ``{{opt.type}}``
+   :runtime updatable: ``{{ runtime_updatable | string | lower }}``
 {%- if default is not none %}
   {%- if opt.type == 'size' %}
    :default: ``{{ default | eval_size | iec_size }}``
@@ -183,6 +184,22 @@ def jinja_template() -> jinja2.Template:
 
 FieldValueT = Union[bool, float, int, str]
 
+RUNTIME_UPDATABLE_TYPES = {
+    'bool',
+    'float',
+    'int',
+    'millisecs',
+    'secs',
+    'size',
+    'uint',
+}
+
+NON_RUNTIME_FLAGS = {
+    'cluster_create',
+    'create',
+    'startup',
+}
+
 
 class CephModule(SphinxDirective):
     """
@@ -221,6 +238,10 @@ class CephOption(ObjectDescription):
               label=_('Default'),
               has_arg=False,
               names=('default',)),
+        Field('runtime_updatable',
+              label=_('Runtime updatable'),
+              has_arg=False,
+              names=('runtime updatable',)),
         Field('type',
               label=_('Type'),
               has_arg=False,
@@ -348,6 +369,23 @@ class CephOption(ObjectDescription):
         return self.options.get('module',
                                 self.env.ref_context.get('ceph:module'))
 
+    @staticmethod
+    def _can_update_at_runtime(opt: Dict[str, FieldValueT],
+                               cur_module: str = '') -> bool:
+        flags = set(opt.get('flags', []))
+        if opt.get('runtime') is True:
+            flags.add('runtime')
+        if cur_module:
+            flags.add('mgr')
+        # Keep this in sync with src/common/options.h: Option::can_update_at_runtime().
+        if flags & NON_RUNTIME_FLAGS:
+            return False
+        if 'runtime' in flags:
+            return True
+        if 'mgr' in flags:
+            return False
+        return opt.get('type') in RUNTIME_UPDATABLE_TYPES
+
     def _render_option(self, name) -> str:
         cur_module = self._current_module()
         if cur_module:
@@ -366,10 +404,12 @@ class CephOption(ObjectDescription):
         desc = opt.get('fmt_desc') or opt.get('long_desc') or opt.get('desc')
         opt_default = opt.get('default')
         default = self.options.get('default', opt_default)
+        runtime_updatable = self._can_update_at_runtime(opt, cur_module)
         try:
             return self.template.render(opt=opt,
                                         desc=desc,
-                                        default=default)
+                                        default=default,
+                                        runtime_updatable=runtime_updatable)
         except Exception as e:
             message = (f'Unable to render option "{name}": {e}. ',
                        f'opt={opt}, desc={desc}, default={default}')