From 220e038dc52c78532e944b02a6ccc75324271655 Mon Sep 17 00:00:00 2001
From: Kefu Chai <kchai@redhat.com>
Date: Thu, 2 Nov 2017 12:19:33 +0800
Subject: [PATCH] doc/mgr: document mgr/plugin using automethod

Signed-off-by: Kefu Chai <kchai@redhat.com>
---
 doc/conf.py         | 30 +++++++++++++++++++++---
 doc/mgr/plugins.rst | 57 ++++++---------------------------------------
 2 files changed, 34 insertions(+), 53 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index d2008e49905a..8a74261fd0db 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -65,6 +65,30 @@ breathe_projects_source = {
              ["rados_types.h", "librados.h"])
 }
 breathe_domain_by_extension = {'py': 'py', 'c': 'c', 'h': 'c', 'cc': 'cxx', 'hpp': 'cxx'}
-pybind = os.path.join(top_level, 'src/pybind')
-if pybind not in sys.path:
-    sys.path.insert(0, pybind)
+
+# mocking ceph_module offered by ceph-mgr. `ceph_module` is required by
+# mgr.mgr_module
+class Dummy(object):
+    def __getattr__(self, _):
+        return lambda *args, **kwargs: None
+
+class Mock(object):
+    __all__ = []
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __call__(self, *args, **kwargs):
+        return Mock()
+
+    @classmethod
+    def __getattr__(cls, name):
+        mock = type(name, (Dummy,), {})
+        mock.__module__ = __name__
+        return mock
+
+sys.modules['ceph_module'] = Mock()
+
+for pybind in [os.path.join(top_level, 'src/pybind'),
+               os.path.join(top_level, 'src/pybind/mgr')]:
+    if pybind not in sys.path:
+        sys.path.insert(0, pybind)
diff --git a/doc/mgr/plugins.rst b/doc/mgr/plugins.rst
index 654c50537bc7..2e025733b0ce 100644
--- a/doc/mgr/plugins.rst
+++ b/doc/mgr/plugins.rst
@@ -100,41 +100,13 @@ to cope with the possibility.
 Note that these accessors must not be called in the modules ``__init__``
 function. This will result in a circular locking exception.
 
-``get(self, data_name)``
+.. py:currentmodule:: mgr_module
+.. automethod:: MgrModule.get
+.. automethod:: MgrModule.get_server
+.. automethod:: MgrModule.list_servers
+.. automethod:: MgrModule.get_metadata
+.. automethod:: MgrModule.get_counter
 
-Fetch named cluster-wide objects such as the OSDMap.  Valid things
-to fetch are osd_crush_map_text, osd_map, osd_map_tree,
-osd_map_crush, config, mon_map, fs_map, osd_metadata, pg_summary,
-df, osd_stats, health, mon_status.
-
-All these structures have their own JSON representations: experiment
-or look at the C++ dump() methods to learn about them.
-
-``get_server(self, hostname)``
-
-Fetch metadata about a particular hostname.  This is information
-that ceph-mgr has gleaned from the daemon metadata reported
-by daemons running on a particular server.
-
-``list_servers(self)``
-
-Like ``get_server``, but gives information about all servers (i.e. all
-unique hostnames that have been mentioned in daemon metadata)
-
-``get_metadata(self, svc_type, svc_id)``
-
-Fetch the daemon metadata for a particular service.  svc_type is one
-of osd or mds, and svc_id is a string (convert OSD integer IDs to strings
-when calling this).
-
-``get_counter(self, svc_type, svc_name, path)``
-
-Fetch the latest performance counter data for a particular counter.  The
-path is a period-separated concatenation of the subsystem and the counter
-name, for example "mds.inodes".
-
-A list of two-tuples of (timestamp, value) is returned.  This may be
-empty if no data is available.
 
 Sending commands
 ----------------
@@ -142,23 +114,8 @@ Sending commands
 A non-blocking facility is provided for sending monitor commands
 to the cluster.
 
-``send_command(self, result, command_str, tag)``
-
-The ``result`` parameter should be an instance of the CommandResult
-class, defined in the same module as MgrModule.  This acts as a
-completion and stores the output of the command.  Use CommandResult.wait()
-if you want to block on completion.
-
-The ``command_str`` parameter is a JSON-serialized command.  This
-uses the same format as the ceph command line, which is a dictionary
-of command arguments, with the extra ``prefix`` key containing the
-command name itself.  Consult MonCommands.h for available commands
-and their expected arguments.
+.. automethod:: MgrModule.send_command
 
-The ``tag`` parameter is used for nonblocking operation: when
-a command completes, the ``notify()`` callback on the MgrModule
-instance is triggered, with notify_type set to "command", and
-notify_id set to the tag of the command.
 
 Implementing standby mode
 -------------------------
-- 
2.47.3