From 7e712a337784426857a912618754a73030cc5389 Mon Sep 17 00:00:00 2001 From: Kevin Carter Date: Wed, 24 Jul 2019 07:15:58 -0500 Subject: [PATCH] Add library documentation within roles Roles can have libraries nested within them. This change adds module documentation to roles whenever the "library" directory exists. This will ensure all nested libraries are automatically documeneted. Change-Id: I7b9d3b1beda62b9941ec9126cb9f3a25a16d74e4 Signed-off-by: Kevin Carter --- doc/source/_exts/ansible-autodoc.py | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/doc/source/_exts/ansible-autodoc.py b/doc/source/_exts/ansible-autodoc.py index 8a81bd9eb..79f0a9d79 100644 --- a/doc/source/_exts/ansible-autodoc.py +++ b/doc/source/_exts/ansible-autodoc.py @@ -279,12 +279,31 @@ class AnsibleAutoPluginDirective(Directive): self.run_returns.append(section) - def _run_module(self, module): + # Document any libraries nested within the role + library_path = os.path.join(role, 'library') + if os.path.exists(library_path): + self.options['documentation'] = True + self.options['examples'] = True + for lib in os.listdir(library_path): + if lib.endswith('.py'): + self._run_module( + module=self.load_module( + filename=os.path.join( + library_path, + lib + ) + ), + module_title='Embedded module: {}'.format(lib), + example_title='Examples for embedded module' + ) + + def _run_module(self, module, module_title="Module Documentation", + example_title="Example Tasks"): if self.options.get('documentation'): docs = self.build_documentation(module=module) self.run_returns.append( self.make_node( - title="Module Documentation", + title=module_title, contents=docs ) ) @@ -293,7 +312,7 @@ class AnsibleAutoPluginDirective(Directive): examples = self.build_examples(module=module) self.run_returns.append( self.make_node( - title="Example Tasks", + title=example_title, contents=examples, content_type='yaml' )