From 93153da893e851567a1e50d93e7fe27431502f6f Mon Sep 17 00:00:00 2001
From: Wojtek Porczyk <woju@invisiblethingslab.com>
Date: Mon, 13 Mar 2017 21:51:03 +0100
Subject: [PATCH] Add documentation for mgmt

QubesOS/qubes-issues#2622
---
 doc/index.rst       |  1 +
 qubes/dochelpers.py |  5 ++++-
 qubes/mgmt.py       | 24 ++++++++++++++++++++++++
 qubes/rngdoc.py     |  1 +
 4 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/doc/index.rst b/doc/index.rst
index bfde6ce6..39c5284f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -19,6 +19,7 @@ manpages and API documentation. For primary user documentation, see
    qubes-exc
    qubes-ext
    qubes-log
+   qubes-mgmt
    qubes-tools/index
    qubes-tests
    qubes-dochelpers
diff --git a/qubes/dochelpers.py b/qubes/dochelpers.py
index 00504f42..45ef93c4 100644
--- a/qubes/dochelpers.py
+++ b/qubes/dochelpers.py
@@ -385,7 +385,10 @@ def check_man_args(app, doctree, docname):
     ''' Checks the manpage for undocumented or obsolete sub-commands and
         options.
     '''
-    command = os.path.split(docname)[1]
+    dirname, command = os.path.split(docname)
+    if os.path.basename(dirname) != 'manpages':
+        return
+
     app.info('Checking arguments for {!r}'.format(command))
     doctree.walk(ManpageCheckVisitor(app, command, doctree))
 
diff --git a/qubes/mgmt.py b/qubes/mgmt.py
index ae617787..80ad898a 100644
--- a/qubes/mgmt.py
+++ b/qubes/mgmt.py
@@ -58,19 +58,36 @@ class PermissionDenied(Exception):
 
 
 def not_in_api(func):
+    '''Decorator for methods not intended to appear in API.
+
+    The decorated method cannot be called from public API using
+    :py:class:`QubesMgmt` class. The method becomes "private", and can be
+    called only as a helper for other methods.
+    '''
     func.not_in_api = True
     return func
 
 class QubesMgmt(object):
+    '''Implementation of Qubes Management API calls
+
+    This class contains all the methods available in the API.
+    '''
     def __init__(self, app, src, method, dest, arg):
+        #: :py:class:`qubes.Qubes` object
         self.app = app
 
+        #: source qube
         self.src = self.app.domains[src.decode('ascii')]
+
+        #: destination qube
         self.dest = self.app.domains[dest.decode('ascii')]
+
+        #: argument
         self.arg = arg.decode('ascii')
 
         self.prepr = ProtocolRepr()
 
+        #: name of the method
         self.method = method.decode('ascii')
 
         untrusted_func_name = self.method
@@ -111,11 +128,13 @@ class QubesMgmt(object):
 
     @not_in_api
     def fire_event_for_permission(self, **kwargs):
+        '''Fire an event on the source qube to check for permission'''
         return self.src.fire_event_pre('mgmt-permission:{}'.format(self.method),
             dest=self.dest, arg=self.arg, **kwargs)
 
     @not_in_api
     def fire_event_for_filter(self, iterable, **kwargs):
+        '''Fire an event on the source qube to filter for permission'''
         for selector in self.fire_event_for_permission(**kwargs):
             iterable = filter(selector, iterable)
         return iterable
@@ -130,6 +149,7 @@ class QubesMgmt(object):
 
     @asyncio.coroutine
     def vm_list(self, untrusted_payload):
+        '''List all the domains'''
         assert self.dest.name == 'dom0'
         assert not self.arg
         assert not untrusted_payload
@@ -145,6 +165,7 @@ class QubesMgmt(object):
 
     @asyncio.coroutine
     def vm_property_list(self, untrusted_payload):
+        '''List all properties on a qube'''
         assert not self.arg
         assert not untrusted_payload
         del untrusted_payload
@@ -155,6 +176,7 @@ class QubesMgmt(object):
 
     @asyncio.coroutine
     def vm_property_get(self, untrusted_payload):
+        '''Get a value of one property'''
         assert self.arg in self.dest.property_list()
         assert not untrusted_payload
         del untrusted_payload
@@ -172,6 +194,7 @@ class QubesMgmt(object):
 
     @asyncio.coroutine
     def vm_property_help(self, untrusted_payload):
+        '''Get help for one property'''
         assert self.arg in self.dest.property_list()
         assert not untrusted_payload
         del untrusted_payload
@@ -187,6 +210,7 @@ class QubesMgmt(object):
 
     @asyncio.coroutine
     def vm_property_reset(self, untrusted_payload):
+        '''Reset a property to a default value'''
         assert self.arg in self.dest.property_list()
         assert not untrusted_payload
         del untrusted_payload
diff --git a/qubes/rngdoc.py b/qubes/rngdoc.py
index 7791145f..205b7ea3 100755
--- a/qubes/rngdoc.py
+++ b/qubes/rngdoc.py
@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 #
 # The Qubes OS Project, https://www.qubes-os.org/
 #