def test_injects_examples_when_found(self):
examples_path = os.sep.join(
[os.path.dirname(__file__), '..', 'data', 'examples'])
service_documenter = ServiceDocumenter('myservice', self.session)
service_documenter.EXAMPLE_PATH = examples_path
contents = service_documenter.document_service().decode('utf-8')
assert 'This is an example' in contents
assert 'This is for another service' not in contents
def test_document_service_no_waiter(self):
# Delete the resource model so that the resource is not documented
# as it may try to look at the waiter model during documentation.
os.remove(self.resource_model_file)
os.remove(self.waiter_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
assert 'Waiters' not in contents
def test_document_service_no_paginators(self):
# Delete the resource model so that the resource is not documented
# as it may try to look at the paginator model during documentation.
os.remove(self.resource_model_file)
os.remove(self.paginator_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
self.assertNotIn('Paginators', contents)
def test_creates_correct_path_to_examples_based_on_service_name(self):
path = os.sep.join(
[os.path.dirname(ibm_boto3.__file__), 'examples', 'myservice.rst'])
path = os.path.realpath(path)
with mock.patch('os.path.isfile') as isfile:
isfile.return_value = False
s = ServiceDocumenter('myservice', self.session)
s.document_service()
assert isfile.call_args_list[-1] == mock.call(path)
def test_documentation(ibm_boto3_session, ibm_botocore_session,
available_resources, service_name):
generated_docs = ServiceDocumenter(
service_name, session=ibm_boto3_session).document_service()
generated_docs = generated_docs.decode('utf-8')
client = ibm_boto3.client(service_name, 'us-east-1')
# Check that all of the services have the appropriate title
_assert_has_title(generated_docs, client)
# Check that all services have the client documented.
_assert_has_client_documentation(generated_docs, service_name, client)
# If the service has resources, make sure the service resource
# is at least documented.
if service_name in available_resources:
resource = ibm_boto3.resource(service_name, 'us-east-1')
_assert_has_resource_documentation(generated_docs, service_name,
resource)
# If the client can paginate, make sure the paginators are documented.
try:
paginator_model = ibm_botocore_session.get_paginator_model(
service_name)
_assert_has_paginator_documentation(
generated_docs,
service_name,
client,
sorted(paginator_model._paginator_config),
)
except DataNotFoundError:
pass
# If the client has waiters, make sure the waiters are documented.
if client.waiter_names:
waiter_model = ibm_botocore_session.get_waiter_model(service_name)
_assert_has_waiter_documentation(generated_docs, service_name, client,
waiter_model)
def test_docs_generated():
"""Verify we can generate the appropriate docs for all services"""
botocore_session = ibm_botocore.session.get_session()
session = ibm_boto3.Session(region_name='us-east-1')
for service_name in session.get_available_services():
generated_docs = ServiceDocumenter(service_name,
session=session).document_service()
generated_docs = generated_docs.decode('utf-8')
client = ibm_boto3.client(service_name, 'us-east-1')
# Check that all of the services have the appropriate title
yield (_assert_has_title, generated_docs, client)
# Check that all services have the client documented.
yield (_assert_has_client_documentation, generated_docs, service_name,
client)
# If the client can paginate, make sure the paginators are documented.
try:
paginator_model = botocore_session.get_paginator_model(
service_name)
yield (_assert_has_paginator_documentation, generated_docs,
service_name, client,
sorted(paginator_model._paginator_config))
except DataNotFoundError:
pass
# If the client has waiters, make sure the waiters are documented
if client.waiter_names:
waiter_model = botocore_session.get_waiter_model(service_name)
yield (_assert_has_waiter_documentation, generated_docs,
service_name, client, waiter_model)
# If the service has resources, make sure the service resource
# is at least documented.
if service_name in session.get_available_resources():
resource = ibm_boto3.resource(service_name, 'us-east-1')
yield (_assert_has_resource_documentation, generated_docs,
service_name, resource)
class TestS3Customizations(BaseDocsFunctionalTests):
def setUp(self):
self.documenter = ServiceDocumenter(
's3', session=Session(region_name='us-east-1'))
self.generated_contents = self.documenter.document_service()
self.generated_contents = self.generated_contents.decode('utf-8')
def test_file_transfer_methods_are_documented(self):
self.assert_contains_lines_in_order([
'.. py:class:: S3.Client',
' * :py:meth:`~S3.Client.download_file`',
' * :py:meth:`~S3.Client.upload_file`',
' .. py:method:: download_file(', ' .. py:method:: upload_file('
], self.generated_contents)
def generate_docs(root_dir, session):
"""Generates the reference documentation for ibm_botocore
This will go through every available AWS service and output ReSTructured
text files documenting each service.
:param root_dir: The directory to write the reference files to. Each
service's reference documentation is loacated at
root_dir/reference/services/service-name.rst
:param session: The ibm_boto3 session
"""
services_doc_path = os.path.join(root_dir, 'reference', 'services')
if not os.path.exists(services_doc_path):
os.makedirs(services_doc_path)
for service_name in session.get_available_services():
docs = ServiceDocumenter(service_name, session).document_service()
service_doc_path = os.path.join(services_doc_path,
service_name + '.rst')
with open(service_doc_path, 'wb') as f:
f.write(docs)
def test_document_service_no_resource(self):
os.remove(self.resource_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
assert 'Service Resource' not in contents
def test_document_service(self):
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
lines = [
'*********',
'MyService',
'*********',
'.. contents:: Table of Contents',
' :depth: 2',
'======',
'Client',
'======',
'.. py:class:: MyService.Client',
' These are the available methods:',
' * :py:meth:`~MyService.Client.sample_operation`',
' **Examples** ',
' Sample Description.',
' ::',
' response = client.sample_operation(',
'==========',
'Paginators',
'==========',
'The available paginators are:',
'* :py:class:`MyService.Paginator.SampleOperation`',
'.. py:class:: MyService.Paginator.SampleOperation',
' .. py:method:: paginate(**kwargs)',
'=======',
'Waiters',
'=======',
'The available waiters are:',
'* :py:class:`MyService.Waiter.SampleOperationComplete`',
'.. py:class:: MyService.Waiter.SampleOperationComplete',
' .. py:method:: wait(**kwargs)',
'================',
'Service Resource',
'================',
'.. py:class:: MyService.ServiceResource()',
" These are the resource's available actions:",
' * :py:meth:`sample_operation()`',
" These are the resource's available sub-resources:",
' * :py:meth:`Sample()`',
" These are the resource's available collections:",
' * :py:attr:`samples`',
' .. py:method:: sample_operation(**kwargs)',
' .. py:method:: Sample(name)',
' .. py:attribute:: samples',
' .. py:method:: all()',
' .. py:method:: filter(**kwargs)',
' .. py:method:: limit(**kwargs)',
' .. py:method:: page_size(**kwargs)',
'======',
'Sample',
'======',
'.. py:class:: MyService.Sample(name)',
" These are the resource's available identifiers:",
' * :py:attr:`name`',
" These are the resource's available attributes:",
' * :py:attr:`bar`',
' * :py:attr:`foo`',
" These are the resource's available actions:",
' * :py:meth:`load()`',
' * :py:meth:`operate()`',
' * :py:meth:`reload()`',
" These are the resource's available waiters:",
' * :py:meth:`wait_until_complete()`',
' .. py:attribute:: name',
' .. py:attribute:: bar',
' .. py:attribute:: foo',
' .. py:method:: load()',
' .. py:method:: operate(**kwargs)',
' .. py:method:: reload()',
' .. py:method:: wait_until_complete(**kwargs)',
]
self.assert_contains_lines_in_order(lines, contents)
def setUp(self):
self.documenter = ServiceDocumenter(
's3', session=Session(region_name='us-east-1'))
self.generated_contents = self.documenter.document_service()
self.generated_contents = self.generated_contents.decode('utf-8')