From 2bae8cb79f3ebc92c61906c1b32d80e4415c9426 Mon Sep 17 00:00:00 2001
From: nicolargo <nicolas@nicolargo.com>
Date: Wed, 14 Jul 2021 19:00:11 +0200
Subject: [PATCH] Add API doc for CPU

---
 glances/outputs/glances_stdout_fields.py | 73 ++++++++++++++++++++++++
 glances/plugins/glances_cpu.py           | 17 +++---
 2 files changed, 83 insertions(+), 7 deletions(-)
 create mode 100644 glances/outputs/glances_stdout_fields.py

diff --git a/glances/outputs/glances_stdout_fields.py b/glances/outputs/glances_stdout_fields.py
new file mode 100644
index 00000000..de7a1391
--- /dev/null
+++ b/glances/outputs/glances_stdout_fields.py
@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+#
+# This file is part of Glances.
+#
+# Copyright (C) 2021 Nicolargo <nicolas@nicolargo.com>
+#
+# Glances is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Glances is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+"""Fields description interface class."""
+
+from pprint import pformat
+
+from glances.logger import logger
+from glances.compat import iteritems
+
+
+class GlancesStdoutFieldsDescription(object):
+
+    """
+    This class manages the fields description display.
+    """
+
+    def __init__(self, config=None, args=None):
+        # Init
+        self.config = config
+        self.args = args
+
+    def end(self):
+        pass
+
+    def update(self,
+               stats,
+               duration=3):
+        """Display issue
+        """
+        print('.. _apidoc:')
+        print('')
+        print('API documentation')
+        print('=================')
+        print('')
+        for plugin in sorted(stats._plugins):
+            print('{}'.format(plugin))
+            print('-' * len(plugin))
+            if stats._plugins[plugin].fields_description:
+                print('')
+                for field, description in iteritems(stats._plugins[plugin].fields_description):
+                    print('* **{}**: {} (unit is *{}*)'.format(field,
+                            description['description'][:-1] if description['description'].endswith('.') else description['description'],
+                            description['unit']))
+                print('')
+                print('Output example:')
+                print('')
+                print('.. code-block:: json')
+                print('')
+                print('    # curl http://localhost:61208/api/3/{}'.format(plugin))
+                print('    ' + pformat(stats._plugins[plugin].get_export()).replace('\n', '\n    '))
+                print('')
+            else:
+                logger.error('No fields_description variable defined for plugin {}'.format(plugin))
+
+        # Return True to exit directly (no refresh)
+        return True
diff --git a/glances/plugins/glances_cpu.py b/glances/plugins/glances_cpu.py
index 781f89b3..90670123 100644
--- a/glances/plugins/glances_cpu.py
+++ b/glances/plugins/glances_cpu.py
@@ -30,7 +30,6 @@ from glances.plugins.glances_plugin import GlancesPlugin
 import psutil
 
 # Fields description
-# {'total': 19.7, 'user': 3.4, 'nice': 0.0, 'system': 2.6, 'idle': 93.0, 'iowait': 0.1, 'irq': 0.0, 'softirq': 0.8, 'steal': 0.0, 'guest': 0.0, 'guest_nice': 0.0, 'time_since_update': 2.1306779384613037, 'cpucore': 4, 'ctx_switches': 11636, 'interrupts': 4463, 'soft_interrupts': 3227, 'syscalls': 0}
 fields_description = {
     'total': {'description': 'Sum of all CPU percentages (except idle).',
               'unit': 'percent'},
@@ -58,16 +57,20 @@ processes that have been *niced*.',
     'steal': {'description': '*(Linux)*: percentage of time a virtual CPU waits for a real \
 CPU while the hypervisor is servicing another virtual processor.',
               'unit': 'percent'},
-    'ctx_sw': {'description': 'number of context switches (voluntary + involuntary) per \
+    'ctx_switches': {'description': 'number of context switches (voluntary + involuntary) per \
 second. A context switch is a procedure that a computer\'s CPU (central \
 processing unit) follows to change from one task (or process) to \
 another while ensuring that the tasks do not conflict.',
-               'unit': 'percent'},
-    'inter': {'description': 'number of interrupts per second.',
-              'unit': 'percent'},
-    'sw_int': {'description': 'number of software interrupts per second. Always set to \
+                     'unit': 'percent'},
+    'interrupts': {'description': 'number of interrupts per second.',
+                   'unit': 'percent'},
+    'soft_interrupts': {'description': 'number of software interrupts per second. Always set to \
 0 on Windows and SunOS.',
-               'unit': 'percent'},
+                        'unit': 'percent'},
+    'cpucore': {'description': 'Total number of CPU core.',
+                'unit': 'count'},
+    'time_since_update': {'description': 'Number of seconds since last update.',
+                          'unit': 'seconds'},
 }
 
 # SNMP OID