From bdfcf7cfc52a70a7a077fc823a3f91e60c71e31c Mon Sep 17 00:00:00 2001
From: Kefu Chai <tchaikov@gmail.com>
Date: Wed, 25 Jun 2025 11:50:24 +0800
Subject: [PATCH] doc/dev/config: Document how to use :confval: directive for
 config options

Add comprehensive guide for documenting configuration options using the
:confval: directive, including naming conventions and cross-referencing.

Previously, the documentation lacked guidance on using the :confval:
directive and the important distinction between regular config options
and mgr module options (which require the mgr/<module>/ namespace
prefix). This change provides detailed examples and best practices for
properly documenting and referencing both types of configuration options.

Signed-off-by: Kefu Chai <tchaikov@gmail.com>
(cherry picked from commit d61f9fffac0a1a0c18cbba89e8c43f469ee55c44)
---
 doc/dev/config.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/doc/dev/config.rst b/doc/dev/config.rst
index 9cb20aee7e864..bad75ba4d319c 100644
--- a/doc/dev/config.rst
+++ b/doc/dev/config.rst
@@ -281,3 +281,52 @@ Flags
 .. describe:: create
 
    option only affects daemon creation
+
+Documentation of Configuration Values
+=====================================
+
+Ceph configuration options are documented on-demand using the ``:confval:``
+directive rather than in a centralized location.
+
+Documenting Configuration Options
+---------------------------------
+
+To document a configuration option, use the ``:confval:`` directive:
+
+.. code-block:: rst
+
+   The check interval can be customized by the ``check_interval`` option:
+
+   .. confval:: mgr/inbox/check_interval
+
+.. note::
+   Ceph-mgr module options must include the ``mgr/<module>/``
+   namespace prefix. In the example above, ``check_interval`` belongs to the
+   ``inbox`` module, so it's documented as ``mgr/inbox/check_interval``.
+
+Referencing Configuration Options
+---------------------------------
+
+Once documented, reference options using the ``:confval:`` role:
+
+.. code-block:: rst
+
+   With the :confval:`mgr/inbox/check_interval` setting, you can customize the
+   check interval.
+
+For regular Ceph options (non-mgr modules), the process is the same but without the module prefix:
+
+.. code-block:: rst
+
+   You can set the initial monitor members with :confval:`mon_initial_members`:
+
+   .. confval:: mon_initial_members
+
+Naming Conventions
+------------------
+
+* **Mgr module options**: Use ``mgr/<module>/<option_name>`` format
+* **Regular options**: Use the option name directly (e.g., ``mon_initial_members``)
+
+This approach ensures consistent cross-referencing throughout the documentation
+while maintaining proper namespacing for different configuration contexts.
-- 
2.39.5