From 81c6da9c2c37a5d34b67e4c09d03fd02446937cf Mon Sep 17 00:00:00 2001
From: Marc Bonnici <marc.bonnici@arm.com>
Date: Tue, 24 Apr 2018 10:59:56 +0100
Subject: [PATCH] Documentation: Add support for generating common target api

---
 doc/build_plugin_docs.py | 40 +++++++++++++++++++++++++++++++++++++---
 doc/source/conf.py       |  4 +++-
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/doc/build_plugin_docs.py b/doc/build_plugin_docs.py
index 1208d4b3..683d83ff 100755
--- a/doc/build_plugin_docs.py
+++ b/doc/build_plugin_docs.py
@@ -20,11 +20,12 @@ import sys
 
 from wa import pluginloader
 from wa.framework.configuration.core import RunConfiguration, MetaConfiguration
-from wa.utils.doc import get_rst_from_plugin, underline, get_params_rst
+from wa.framework.target.descriptor import list_target_descriptions
+from wa.utils.doc import (strip_inlined_text, get_rst_from_plugin,
+                          get_params_rst, underline)
 from wa.utils.misc import capitalize
 
-
-GENERATE_FOR_PLUGIN = ['workload', 'instrument', 'output_processor', 'target']
+GENERATE_FOR_PLUGIN = ['workload', 'instrument', 'output_processor']
 
 
 def generate_plugin_documentation(source_dir, outdir, ignore_paths):
@@ -45,6 +46,39 @@ def generate_plugin_documentation(source_dir, outdir, ignore_paths):
             for ext in sorted(exts, key=lambda x: x.name):
                 wfh.write(get_rst_from_plugin(ext))
 
+def generate_target_documentation(outdir):
+    targets_to_generate = ['generic_android',
+                           'generic_linux',
+                           'generic_chromeos',
+                           'generic_local',
+                           'juno_linux',
+                           'juno_android']
+
+    intro = '\nThis is a list of commonly used targets and their device '\
+    'parameters, to see a complete for a complete reference please use the '\
+    'WA :ref:`list command <list-command>`.\n\n\n'
+
+    pluginloader.clear()
+    pluginloader.update(packages=['wa.framework.target.descriptor'])
+
+    target_descriptors = list_target_descriptions(pluginloader)
+    outfile = os.path.join(outdir, 'targets.rst')
+    with open(outfile, 'w') as wfh:
+        wfh.write(underline('Common Targets'))
+        wfh.write(intro)
+        for td in sorted(target_descriptors, key=lambda t: t.name):
+            if td.name not in targets_to_generate:
+                continue
+            text = underline(td.name, '~')
+            if hasattr(td, 'description'):
+                desc = strip_inlined_text(td.description or '')
+                text += desc
+            text += underline('Device Parameters:', '-')
+            text += get_params_rst(td.conn_params)
+            text += get_params_rst(td.platform_params)
+            text += get_params_rst(td.target_params)
+            text += get_params_rst(td.assistant_params)
+            wfh.write(text)
 
 def generate_run_config_documentation(outdir):
     generate_config_documentation(RunConfiguration, outdir)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index fc00f687..52386faf 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -31,7 +31,8 @@ sys.path.insert(0, os.path.join(this_dir, '../..'))
 import wa
 from build_plugin_docs import (generate_plugin_documentation,
                                generate_run_config_documentation,
-                               generate_meta_config_documentation)
+                               generate_meta_config_documentation,
+                               generate_target_documentation)
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -318,6 +319,7 @@ def setup(app):
     os.chdir(os.path.dirname(__file__))
     app.connect('builder-inited', run_apidoc)
     generate_plugin_documentation(module_dir, 'plugins', excluded_extensions)
+    generate_target_documentation('plugins')
     generate_run_config_documentation('run_config')
     generate_meta_config_documentation('run_config')
     app.add_object_type('confval', 'confval',