| 21 | |
| 22 | |
| 23 | class WaiterDocumenter: |
| 24 | def __init__(self, client, service_waiter_model, root_docs_path): |
| 25 | self._client = client |
| 26 | self._client_class_name = self._client.__class__.__name__ |
| 27 | self._service_name = self._client.meta.service_model.service_name |
| 28 | self._service_waiter_model = service_waiter_model |
| 29 | self._root_docs_path = root_docs_path |
| 30 | self._USER_GUIDE_LINK = ( |
| 31 | 'https://boto3.amazonaws.com/' |
| 32 | 'v1/documentation/api/latest/guide/clients.html#waiters' |
| 33 | ) |
| 34 | |
| 35 | def document_waiters(self, section): |
| 36 | """Documents the various waiters for a service. |
| 37 | |
| 38 | :param section: The section to write to. |
| 39 | """ |
| 40 | section.style.h2('Waiters') |
| 41 | self._add_overview(section) |
| 42 | section.style.new_line() |
| 43 | section.writeln('The available waiters are:') |
| 44 | section.style.toctree() |
| 45 | for waiter_name in self._service_waiter_model.waiter_names: |
| 46 | section.style.tocitem(f'{self._service_name}/waiter/{waiter_name}') |
| 47 | # Create a new DocumentStructure for each waiter and add contents. |
| 48 | waiter_doc_structure = DocumentStructure( |
| 49 | waiter_name, target='html' |
| 50 | ) |
| 51 | self._add_single_waiter(waiter_doc_structure, waiter_name) |
| 52 | # Write waiters in individual/nested files. |
| 53 | # Path: <root>/reference/services/<service>/waiter/<waiter_name>.rst |
| 54 | waiter_dir_path = os.path.join( |
| 55 | self._root_docs_path, self._service_name, 'waiter' |
| 56 | ) |
| 57 | waiter_doc_structure.write_to_file(waiter_dir_path, waiter_name) |
| 58 | |
| 59 | def _add_single_waiter(self, section, waiter_name): |
| 60 | section.add_title_section(waiter_name) |
| 61 | waiter_section = section.add_new_section(waiter_name) |
| 62 | waiter_section.style.start_sphinx_py_class( |
| 63 | class_name=f"{self._client_class_name}.Waiter.{waiter_name}" |
| 64 | ) |
| 65 | |
| 66 | # Add example on how to instantiate waiter. |
| 67 | waiter_section.style.start_codeblock() |
| 68 | waiter_section.style.new_line() |
| 69 | waiter_section.write( |
| 70 | f'waiter = client.get_waiter(\'{xform_name(waiter_name)}\')' |
| 71 | ) |
| 72 | waiter_section.style.end_codeblock() |
| 73 | |
| 74 | # Add information on the wait() method |
| 75 | waiter_section.style.new_line() |
| 76 | document_wait_method( |
| 77 | section=waiter_section, |
| 78 | waiter_name=waiter_name, |
| 79 | event_emitter=self._client.meta.events, |
| 80 | service_model=self._client.meta.service_model, |
no outgoing calls