Add html meta description

This adds an html meta description only to service and operation pages.

Author: kdaily

awscli/bcdoc/docevents.py

@@ -13,6 +13,7 @@
 
 
 DOC_EVENTS = {
+    'doc-meta-description': '.%s',
     'doc-breadcrumbs': '.%s',
     'doc-title': '.%s',
     'doc-description': '.%s',
@@ -39,6 +40,8 @@ def generate_events(session, help_command):
     # Now generate the documentation events
     session.emit('doc-breadcrumbs.%s' % help_command.event_class,
                  help_command=help_command)
+    session.emit('doc-meta-description.%s' % help_command.event_class,
+                 help_command=help_command)
     session.emit('doc-title.%s' % help_command.event_class,
                  help_command=help_command)
     session.emit('doc-description.%s' % help_command.event_class,

awscli/clidocs.py

@@ -17,7 +17,7 @@
 from botocore.model import StringShape
 from botocore.utils import is_json_value_header
 
-from awscli import SCALAR_TYPES
+from awscli import SCALAR_TYPES, __version__ as AWS_CLI_VERSION
 from awscli.argprocess import ParamShorthandDocGen
 from awscli.bcdoc.docevents import DOC_EVENTS
 from awscli.topictags import TopicTagDB
@@ -114,7 +114,8 @@ def doc_breadcrumbs(self, help_command, **kwargs):
                 full_cmd_list.append(cmd)
                 full_cmd_name = ' '.join(full_cmd_list)
                 doc.write(f':ref:`{cmd} <cli:{full_cmd_name}>`')
-            doc.write(' ]')
+            doc.writeln(' ]')
+            doc.writeln('')
 
     def doc_title(self, help_command, **kwargs):
         doc = help_command.doc
@@ -223,6 +224,9 @@ def doc_relateditem(self, help_command, related_item, **kwargs):
         )
         doc.write('\n')
 
+    def doc_meta_description(self, help_command, **kwargs):
+        pass
+
     def _document_enums(self, model, doc):
         """Documents top-level parameter enums"""
         if isinstance(model, StringShape):
@@ -402,6 +406,13 @@ def doc_subitem(self, command_name, help_command, **kwargs):
         else:
             doc.style.tocitem(command_name)
 
+    def doc_meta_description(self, help_command, **kwargs):
+        doc = help_command.doc
+        reference = help_command.event_class.replace('.', ' ')
+        doc.writeln(".. meta::")
+        doc.writeln(f"   :description: Learn about the AWS CLI {AWS_CLI_VERSION} {reference} commands.")
+        doc.writeln("")
+
 
 class OperationDocumentEventHandler(CLIDocumentEventHandler):
     AWS_DOC_BASE = 'https://docs.aws.amazon.com/goto/WebAPI'
@@ -618,6 +629,12 @@ def doc_output(self, help_command, event_name, **kwargs):
             for member_name, member_shape in output_shape.members.items():
                 self._doc_member(doc, member_name, member_shape, stack=[])
 
+    def doc_meta_description(self, help_command, **kwargs):
+        doc = help_command.doc
+        reference = help_command.event_class.replace('.', ' ')
+        doc.writeln(".. meta::")
+        doc.writeln(f"   :description: Use the AWS CLI {AWS_CLI_VERSION} to run the {reference} command.")
+        doc.writeln("")
 
 class TopicListerDocumentEventHandler(CLIDocumentEventHandler):
     DESCRIPTION = (

tests/unit/test_clidocs.py

@@ -18,7 +18,8 @@
 from awscli.testutils import mock, unittest, FileCreator
 from awscli.clidocs import OperationDocumentEventHandler, \
     CLIDocumentEventHandler, TopicListerDocumentEventHandler, \
-    TopicDocumentEventHandler, GlobalOptionsDocumenter
+    TopicDocumentEventHandler, GlobalOptionsDocumenter, \
+    ServiceDocumentEventHandler
 from awscli.bcdoc.restdoc import ReSTDocument
 from awscli.help import ServiceHelpCommand, TopicListerCommand, \
     TopicHelpCommand, HelpCommand
@@ -195,7 +196,7 @@ def test_breadcrumbs_html(self):
         doc_handler.doc_breadcrumbs(help_cmd)
         self.assertEqual(
             help_cmd.doc.getvalue().decode('utf-8'),
-            '[ :ref:`aws <cli:aws>` ]'
+            '[ :ref:`aws <cli:aws>` ]\n\n'
         )
 
     def test_breadcrumbs_service_command_html(self):
@@ -208,7 +209,7 @@ def test_breadcrumbs_service_command_html(self):
         doc_handler.doc_breadcrumbs(help_cmd)
         self.assertEqual(
             help_cmd.doc.getvalue().decode('utf-8'),
-            '[ :ref:`aws <cli:aws>` ]'
+            '[ :ref:`aws <cli:aws>` ]\n\n'
         )
 
     def test_breadcrumbs_operation_command_html(self):
@@ -221,7 +222,7 @@ def test_breadcrumbs_operation_command_html(self):
         doc_handler.doc_breadcrumbs(help_cmd)
         self.assertEqual(
             help_cmd.doc.getvalue().decode('utf-8'),
-            '[ :ref:`aws <cli:aws>` . :ref:`ec2 <cli:aws ec2>` ]'
+            '[ :ref:`aws <cli:aws>` . :ref:`ec2 <cli:aws ec2>` ]\n\n'
         )
 
     def test_breadcrumbs_wait_command_html(self):
@@ -235,7 +236,7 @@ def test_breadcrumbs_wait_command_html(self):
         self.assertEqual(
             help_cmd.doc.getvalue().decode('utf-8'),
             ('[ :ref:`aws <cli:aws>` . :ref:`s3api <cli:aws s3api>`'
-             ' . :ref:`wait <cli:aws s3api wait>` ]')
+             ' . :ref:`wait <cli:aws s3api wait>` ]\n\n')
         )
 
     def test_documents_json_header_shape(self):
@@ -444,6 +445,32 @@ def test_tagged_union_comes_after_docstring_output(self):
         rendered = help_command.doc.getvalue().decode('utf-8')
         self.assertRegex(rendered, r'FooBar[\s\S]*Tagged Union')
 
+    def test_meta_description_operation_command_html(self):
+        help_cmd = ServiceHelpCommand(
+            self.session, self.obj, self.command_table, self.arg_table,
+            self.name, 'ec2.run-instances'
+        )
+        help_cmd.doc.target = 'html'
+        doc_handler = OperationDocumentEventHandler(help_cmd)
+        doc_handler.doc_meta_description(help_cmd)
+
+        meta_description = help_cmd.doc.getvalue().decode('utf-8')
+        self.assertIn(".. meta::\n   :description: ", meta_description)
+        self.assertIn('to run the ec2 run-instances command', meta_description)
+
+    def test_meta_description_service_html(self):
+        help_cmd = ServiceHelpCommand(
+            self.session, self.obj, self.command_table, self.arg_table,
+            self.name, 'ec2'
+        )
+        help_cmd.doc.target = 'html'
+        doc_handler = ServiceDocumentEventHandler(help_cmd)
+        doc_handler.doc_meta_description(help_cmd)
+
+        meta_description = help_cmd.doc.getvalue().decode('utf-8')
+        self.assertIn(".. meta::\n   :description: Learn about the AWS CLI ", meta_description)
+        self.assertIn(' ec2 commands', meta_description)
+
 
 class TestTopicDocumentEventHandlerBase(unittest.TestCase):
     def setUp(self):