From: Kefu Chai <kchai@redhat.com>
Date: Sun, 28 Mar 2021 15:25:02 +0000 (+0800)
Subject: doc: add a new directive "confval"
X-Git-Tag: v17.1.0~2433^2~2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=754bd73d2bdadeac40981fc2947d8d8cb20c9197;p=ceph.git

doc: add a new directive "confval"

* so we can define configuration in a more structured way
* so the confvals can be cross referenced

see also https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_object_type

Signed-off-by: Kefu Chai <kchai@redhat.com>
---

diff --git a/doc/conf.py b/doc/conf.py
index 7b6b50c0e86f..ad36c0950f8d 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -6,6 +6,11 @@ import sys
 import yaml
 import sphinx.util
 
+from sphinx.domains.python import PyField
+from sphinx.locale import _
+from sphinx.util.docfields import Field
+
+
 top_level = \
     os.path.dirname(
         os.path.dirname(
@@ -235,3 +240,36 @@ def setup(app):
                 generate_state_diagram(['src/osd/PeeringState.h',
                                         'src/osd/PeeringState.cc'],
                                        'doc/dev/peering_graph.generated.dot'))
+
+    app.add_object_type(
+        'confval',
+        'confval',
+        objname='configuration value',
+        indextemplate='pair: %s; configuration value',
+        doc_field_types=[
+            PyField(
+                'type',
+                label=_('Type'),
+                has_arg=False,
+                names=('type',),
+                bodyrolename='class'
+            ),
+            Field(
+                'default',
+                label=_('Default'),
+                has_arg=False,
+                names=('default',),
+            ),
+            Field(
+                'required',
+                label=_('Required'),
+                has_arg=False,
+                names=('required',),
+            ),
+            Field(
+                'example',
+                label=_('Example'),
+                has_arg=False,
+            )
+        ]
+    )