Merge pull request #40847 from tchaikov/wip-doc-build

admin/build-doc: use htmldir builder for livehtml

Reviewed-by: Josh Durgin <jdurgin@redhat.com>

admin/build-doc

@@ -96,7 +96,7 @@ for target in $sphinx_targets; do
             ;;
         livehtml)
             $vdir/bin/pip install --quiet sphinx-autobuild
-            $vdir/bin/sphinx-autobuild --re-ignore '.*\.dot' "$@" \
+            $vdir/bin/sphinx-autobuild --re-ignore '.*\.dot' -b dirhtml "$@" \
                                        $TOPDIR/doc $TOPDIR/build-doc/output/html
             ;;
     esac

admin/doc-requirements.txt

@@ -1,4 +1,4 @@
-Sphinx >= 3.2.1
+Sphinx == 3.5.4
 git+https://github.com/ceph/sphinx-ditaa.git@py3#egg=sphinx-ditaa
 breathe >= 4.20.0
 Jinja2
@@ -8,7 +8,7 @@ pcpp
 prettytable
 sphinx-autodoc-typehints
 sphinx-prompt
-sphinx_rtd_theme >=0.4.3
+sphinx_rtd_theme == 0.5.2
 Sphinx-Substitution-Extensions
 typed-ast
 sphinxcontrib-openapi

doc/_ext/ceph_confval.py

@@ -0,0 +1,43 @@
+from sphinx.domains.python import PyField
+from sphinx.locale import _
+from sphinx.util.docfields import Field
+
+
+def setup(app):
+    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,
+            )
+        ]
+    )
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

doc/_ext/ceph_releases.py

@@ -210,3 +210,7 @@ class CephTimeline(Directive):
 def setup(app):
     app.add_directive('ceph_releases', CephReleases)
     app.add_directive('ceph_timeline', CephTimeline)
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True
+    }

doc/conf.py

@@ -6,10 +6,6 @@ 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(
@@ -123,6 +119,7 @@ extensions = [
     'breathe',
     'ceph_commands',
     'ceph_releases',
+    'ceph_confval',
     'sphinxcontrib.openapi'
     ]
 
@@ -240,36 +237,3 @@ 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,
-            )
-        ]
-    )

src/include/rados/librados.h

@@ -2381,7 +2381,7 @@ typedef void (*rados_watchcb_t)(uint8_t opcode, uint64_t ver, void *arg);
  * @param handle the watcher handle we are notifying
  * @param notifier_id the unique client id for the notifier
  * @param data payload from the notifier
- * @param datalen length of payload buffer
+ * @param data_len length of payload buffer
  */
 typedef void (*rados_watchcb2_t)(void *arg,
 				 uint64_t notify_id,
@@ -2400,6 +2400,7 @@ typedef void (*rados_watchcb2_t)(void *arg,
  * we may have missed notify events.
  *
  * @param pre opaque user-defined value provided to rados_watch2()
+ * @param cookie the internal id assigned to the watch session
  * @param err error code
  */
   typedef void (*rados_watcherrcb_t)(void *pre, uint64_t cookie, int err);