class TopicListerDocumentEventHandler(CLIDocumentEventHandler):
DESCRIPTION = (
'This is the AWS CLI Topic Guide. It gives access to a set '
'of topics that provide a deeper understanding of the CLI. To access '
'the list of topics from the command line, run ``aws help topics``. '
'To access a specific topic from the command line, run '
'``aws help [topicname]``, where ``topicname`` is the name of the '
'topic as it appears in the output from ``aws help topics``.')
def __init__(self, help_command):
self.help_command = help_command
self.register(help_command.session, help_command.event_class)
self._topic_tag_db = TopicTagDB()
self._topic_tag_db.load_json_index()
def doc_breadcrumbs(self, help_command, **kwargs):
doc = help_command.doc
if doc.target != 'man':
doc.write('[ ')
doc.style.sphinx_reference_label(label='cli:aws', text='aws')
doc.write(' ]')
def doc_title(self, help_command, **kwargs):
doc = help_command.doc
doc.style.new_paragraph()
doc.style.link_target_definition(
refname='cli:aws help %s' % self.help_command.name,
link='')
doc.style.h1('AWS CLI Topic Guide')
def doc_description(self, help_command, **kwargs):
doc = help_command.doc
doc.style.h2('Description')
doc.include_doc_string(self.DESCRIPTION)
doc.style.new_paragraph()
def doc_synopsis_start(self, help_command, **kwargs):
pass
def doc_synopsis_end(self, help_command, **kwargs):
pass
def doc_options_start(self, help_command, **kwargs):
pass
def doc_options_end(self, help_command, **kwargs):
pass
def doc_subitems_start(self, help_command, **kwargs):
doc = help_command.doc
doc.style.h2('Available Topics')
categories = self._topic_tag_db.query('category')
topic_names = self._topic_tag_db.get_all_topic_names()
# Sort the categories
category_names = sorted(categories.keys())
for category_name in category_names:
doc.style.h3(category_name)
doc.style.new_paragraph()
# Write out the topic and a description for each topic under
# each category.
for topic_name in sorted(categories[category_name]):
description = self._topic_tag_db.get_tag_single_value(
topic_name, 'description')
doc.write('* ')
doc.style.sphinx_reference_label(
label='cli:aws help %s' % topic_name,
text=topic_name
)
doc.write(': %s\n' % description)
# Add a hidden toctree to make sure everything is connected in
# the document.
doc.style.hidden_toctree()
for topic_name in topic_names:
doc.style.hidden_tocitem(topic_name)
class TopicListerDocumentEventHandler(CLIDocumentEventHandler):
DESCRIPTION = (
'This is the AWS CLI Topic Guide. It gives access to a set '
'of topics that provide a deeper understanding of the CLI. To access '
'the list of topics from the command line, run ``aws help topics``. '
'To access a specific topic from the command line, run '
'``aws help [topicname]``, where ``topicname`` is the name of the '
'topic as it appears in the output from ``aws help topics``.')
def __init__(self, help_command):
self.help_command = help_command
self.register(help_command.session, help_command.event_class)
self.help_command.doc.translation_map = self.build_translation_map()
self._topic_tag_db = TopicTagDB()
self._topic_tag_db.load_json_index()
def doc_breadcrumbs(self, help_command, **kwargs):
doc = help_command.doc
if doc.target != 'man':
doc.write('[ ')
doc.style.sphinx_reference_label(label='cli:aws', text='aws')
doc.write(' ]')
def doc_title(self, help_command, **kwargs):
doc = help_command.doc
doc.style.new_paragraph()
doc.style.link_target_definition(
refname='cli:aws help %s' % self.help_command.name,
link='')
doc.style.h1('AWS CLI Topic Guide')
def doc_description(self, help_command, **kwargs):
doc = help_command.doc
doc.style.h2('Description')
doc.include_doc_string(self.DESCRIPTION)
doc.style.new_paragraph()
def doc_synopsis_start(self, help_command, **kwargs):
pass
def doc_synopsis_end(self, help_command, **kwargs):
pass
def doc_options_start(self, help_command, **kwargs):
pass
def doc_options_end(self, help_command, **kwargs):
pass
def doc_subitems_start(self, help_command, **kwargs):
doc = help_command.doc
doc.style.h2('Available Topics')
categories = self._topic_tag_db.query('category')
topic_names = self._topic_tag_db.get_all_topic_names()
# Sort the categories
category_names = sorted(categories.keys())
for category_name in category_names:
doc.style.h3(category_name)
doc.style.new_paragraph()
# Write out the topic and a description for each topic under
# each category.
for topic_name in sorted(categories[category_name]):
description = self._topic_tag_db.get_tag_single_value(
topic_name, 'description')
doc.write('* ')
doc.style.sphinx_reference_label(
label='cli:aws help %s' % topic_name,
text=topic_name
)
doc.write(': %s\n' % description)
# Add a hidden toctree to make sure everything is connected in
# the document.
doc.style.hidden_toctree()
for topic_name in topic_names:
doc.style.hidden_tocitem(topic_name)
class TestTopicTagDBQuery(TestTopicTagDB):
def test_query_all_tags_single_topic(self):
tag_dict = {
'topic-name-1': {
'title': ['My First Topic Title'],
'description': ['This describes my first topic'],
'category': ['General Topics'],
'related command': ['aws s3'],
'related topic': ['topic-name-2']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
# Check title query
query_dict = self.topic_tag_db.query('title')
self.assertEqual(query_dict,
{'My First Topic Title': ['topic-name-1']})
# Check the description query
query_dict = self.topic_tag_db.query('description')
self.assertEqual(query_dict,
{'This describes my first topic': ['topic-name-1']})
# Check the category query
query_dict = self.topic_tag_db.query('category')
self.assertEqual(query_dict, {'General Topics': ['topic-name-1']})
# Check the related command query
query_dict = self.topic_tag_db.query('related command')
self.assertEqual(query_dict, {'aws s3': ['topic-name-1']})
# Check the description query
query_dict = self.topic_tag_db.query('related topic')
self.assertEqual(query_dict, {'topic-name-2': ['topic-name-1']})
def test_query_tag_multi_values(self):
tag_dict = {'topic-name-1': {'related topic': ['foo', 'bar']}}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('related topic')
self.assertEqual(query_dict, {
'foo': ['topic-name-1'],
'bar': ['topic-name-1']
})
def test_query_tag_multi_values(self):
tag_dict = {'topic-name-1': {'related topic': ['foo', 'bar']}}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('related topic')
self.assertEqual(query_dict, {
'foo': ['topic-name-1'],
'bar': ['topic-name-1']
})
def test_query_multiple_topics(self):
tag_dict = {
'topic-name-1': {
'category': ['foo']
},
'topic-name-2': {
'category': ['bar']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category')
self.assertEqual(query_dict, {
'foo': ['topic-name-1'],
'bar': ['topic-name-2']
})
def test_query_multiple_topics_with_multi_values(self):
tag_dict = {
'topic-name-1': {
'category': ['foo', 'bar']
},
'topic-name-2': {
'category': ['baz', 'biz']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category')
self.assertEqual(
query_dict, {
'foo': ['topic-name-1'],
'bar': ['topic-name-1'],
'baz': ['topic-name-2'],
'biz': ['topic-name-2']
})
def test_query_multiple_topics_with_overlap_values(self):
tag_dict = {
'topic-name-1': {
'category': ['foo', 'bar']
},
'topic-name-2': {
'category': ['bar', 'biz']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category')
self.assertCountEqual(
query_dict, {
'foo': ['topic-name-1'],
'biz': ['topic-name-2'],
'bar': ['topic-name-1', 'topic-name-2']
})
def test_query_with_limit_single_value(self):
tag_dict = {
'topic-name-1': {
'category': ['foo', 'bar']
},
'topic-name-2': {
'category': ['bar', 'biz']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category', ['bar'])
self.assertCountEqual(query_dict,
{'bar': ['topic-name-1', 'topic-name-2']})
def test_query_with_limit_multi_value(self):
tag_dict = {
'topic-name-1': {
'category': ['foo', 'bar']
},
'topic-name-2': {
'category': ['bar', 'biz']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category', ['foo', 'bar'])
self.assertCountEqual(query_dict, {
'foo': ['topic-name-1'],
'bar': ['topic-name-1', 'topic-name-2']
})
def topic_query_with_non_existant_tag(self):
tag_dict = {'topic-name-1': {'category': ['foo']}}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query(':bar:')
self.assertEqual(query_dict, {})
class TestTopicTagDBQuery(TestTopicTagDB):
def test_query_all_tags_single_topic(self):
tag_dict = {
'topic-name-1': {
'title': ['My First Topic Title'],
'description': ['This describes my first topic'],
'category': ['General Topics'],
'related command': ['aws s3'],
'related topic': ['topic-name-2']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
# Check title query
query_dict = self.topic_tag_db.query('title')
self.assertEqual(query_dict,
{'My First Topic Title': ['topic-name-1']})
# Check the description query
query_dict = self.topic_tag_db.query('description')
self.assertEqual(query_dict,
{'This describes my first topic': ['topic-name-1']})
# Check the category query
query_dict = self.topic_tag_db.query('category')
self.assertEqual(query_dict,
{'General Topics': ['topic-name-1']})
# Check the related command query
query_dict = self.topic_tag_db.query('related command')
self.assertEqual(query_dict,
{'aws s3': ['topic-name-1']})
# Check the description query
query_dict = self.topic_tag_db.query('related topic')
self.assertEqual(query_dict,
{'topic-name-2': ['topic-name-1']})
def test_query_tag_multi_values(self):
tag_dict = {
'topic-name-1': {
'related topic': ['foo', 'bar']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('related topic')
self.assertEqual(query_dict,
{'foo': ['topic-name-1'], 'bar': ['topic-name-1']})
def test_query_tag_multi_values(self):
tag_dict = {
'topic-name-1': {
'related topic': ['foo', 'bar']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('related topic')
self.assertEqual(query_dict,
{'foo': ['topic-name-1'], 'bar': ['topic-name-1']})
def test_query_multiple_topics(self):
tag_dict = {
'topic-name-1': {
'category': ['foo']
},
'topic-name-2': {
'category': ['bar']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category')
self.assertEqual(query_dict,
{'foo': ['topic-name-1'], 'bar': ['topic-name-2']})
def test_query_multiple_topics_with_multi_values(self):
tag_dict = {
'topic-name-1': {
'category': ['foo', 'bar']
},
'topic-name-2': {
'category': ['baz', 'biz']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category')
self.assertEqual(query_dict,
{'foo': ['topic-name-1'], 'bar': ['topic-name-1'],
'baz': ['topic-name-2'], 'biz': ['topic-name-2']})
def test_query_multiple_topics_with_overlap_values(self):
tag_dict = {
'topic-name-1': {
'category': ['foo', 'bar']
},
'topic-name-2': {
'category': ['bar', 'biz']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category')
self.assertCountEqual(
query_dict, {'foo': ['topic-name-1'], 'biz': ['topic-name-2'],
'bar': ['topic-name-1', 'topic-name-2']})
def test_query_with_limit_single_value(self):
tag_dict = {
'topic-name-1': {
'category': ['foo', 'bar']
},
'topic-name-2': {
'category': ['bar', 'biz']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category', ['bar'])
self.assertCountEqual(query_dict,
{'bar': ['topic-name-1', 'topic-name-2']})
def test_query_with_limit_multi_value(self):
tag_dict = {
'topic-name-1': {
'category': ['foo', 'bar']
},
'topic-name-2': {
'category': ['bar', 'biz']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query('category', ['foo', 'bar'])
self.assertCountEqual(query_dict,
{'foo': ['topic-name-1'],
'bar': ['topic-name-1', 'topic-name-2']})
def topic_query_with_non_existant_tag(self):
tag_dict = {
'topic-name-1': {
'category': ['foo']
}
}
self.topic_tag_db = TopicTagDB(tag_dict)
query_dict = self.topic_tag_db.query(':bar:')
self.assertEqual(query_dict, {})
