summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authornicolargo <nicolas@nicolargo.com>2021-07-16 16:44:11 +0200
committernicolargo <nicolas@nicolargo.com>2021-07-16 16:44:11 +0200
commit10ae52bea6153c00c1c0fbf6ce50b05e0fbd147c (patch)
tree7e483558a539f83a3193591b7e5da205bb0a8e3f
parent2c92670771061f7eb63588494032cb34cf4958bb (diff)
Rename stdout fields to apidoc
-rw-r--r--glances/outputs/glances_stdout_apidoc.py159
1 files changed, 159 insertions, 0 deletions
diff --git a/glances/outputs/glances_stdout_apidoc.py b/glances/outputs/glances_stdout_apidoc.py
new file mode 100644
index 00000000..63e98ee8
--- /dev/null
+++ b/glances/outputs/glances_stdout_apidoc.py
@@ -0,0 +1,159 @@
+# -*- 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
+import json
+
+from glances.logger import logger
+from glances.compat import iteritems
+
+API_URL = "http://localhost:61208/api/3"
+
+APIDOC_HEADER = """\
+.. _api:
+
+API (Restfull/JSON) documentation
+=================================
+
+The Glances Restfull/API server could be ran using the following command line:
+
+.. code-block:: bash
+
+ # glances -w --disable-webui
+
+Note: Change request URL api/3 by api/2 if you use Glances 2.x.
+"""
+
+
+def indent_stat(stat, indent=' '):
+ # Indent stats to pretty print it
+ if isinstance(stat, list) and len(stat) > 1 and isinstance(stat[0], dict):
+ # Only display two first items
+ return indent + pformat(stat[0:2]).replace('\n', '\n' + indent)
+ else:
+ return indent + pformat(stat).replace('\n', '\n' + indent)
+
+
+def get_plugins_list(stat):
+ return """\
+GET Plugins list
+----------------
+
+.. code-block:: json
+
+ # curl {}/pluginslist
+{}
+
+""".format(API_URL,
+ indent_stat(stat))
+
+
+class GlancesStdoutApiDoc(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
+ """
+
+ # Display header
+ print(APIDOC_HEADER)
+
+ # Display plugins list
+ print(get_plugins_list(sorted(stats._plugins)))
+
+ # Loop over plugins
+ for plugin in sorted(stats._plugins):
+ stat = stats.get_plugin(plugin)
+ stat_export = stat.get_export()
+
+ if stat_export is None or stat_export == [] or stat_export == {}:
+ continue
+
+ sub_title = 'GET {}'.format(plugin)
+ print(sub_title)
+ print('-' * len(sub_title))
+ print('')
+
+ print('.. code-block:: json')
+ print('')
+ print(' # curl {}/{}'.format(API_URL, plugin))
+ print(indent_stat(stat_export))
+ print('')
+
+ if stat.fields_description:
+ # For each plugins with a description
+ print('Fields descriptions:')
+ print('')
+ for field, description in iteritems(stat.fields_description):
+ print('* **{}**: {} (unit is *{}*)'.format(field,
+ description['description'][:-1] if description['description'].endswith('.') else description['description'],
+ description['unit']))
+ print('')
+ else:
+ logger.error('No fields_description variable defined for plugin {}'.format(plugin))
+
+ item = None
+ value = None
+ if isinstance(stat_export, dict):
+ item = list(stat_export.keys())[0]
+ value = None
+ elif isinstance(stat_export, list) and len(stat_export) > 0 and isinstance(stat_export[0], dict):
+ if 'key' in stat_export[0]:
+ item = stat_export[0]['key']
+ else:
+ item = list(stat_export[0].keys())[0]
+ if item and stat.get_stats_item(item):
+ stat_item = json.loads(stat.get_stats_item(item))
+ if isinstance(stat_item[item], list):
+ value = stat_item[item][0]
+ else:
+ value = stat_item[item]
+ print('Get a specific field:')
+ print('')
+ print('.. code-block:: json')
+ print('')
+ print(' # curl {}/{}/{}'.format(API_URL, plugin, item))
+ print(indent_stat(stat_item))
+ print('')
+ if item and value and stat.get_stats_value(item, value):
+ print('Get a specific item when field matchs the given value:')
+ print('')
+ print('.. code-block:: json')
+ print('')
+ print(' # curl {}/{}/{}/{}'.format(API_URL, plugin, item, value))
+ print(indent_stat(json.loads(stat.get_stats_value(item, value))))
+ print('')
+
+ # Return True to exit directly (no refresh)
+ return True