Better auto-generated documentation and fixed docstring warnings

This commit is contained in:
Fabio Manganiello 2022-03-03 15:15:55 +01:00
parent 7c9e9d284d
commit fdf6d8fb4e
Signed by: blacklight
GPG key ID: D90FBA7F76362774
12 changed files with 85 additions and 58 deletions

View file

@ -1,3 +1,4 @@
import inspect
import os
from platypush.backend import Backend
@ -6,11 +7,17 @@ from platypush.plugins import Plugin
from platypush.utils.manifest import get_manifests
def _get_inspect_plugin():
p = get_plugin('inspect')
assert p, 'Could not load the `inspect` plugin'
return p
def get_all_plugins():
manifests = {mf.component_name for mf in get_manifests(Plugin)}
return {
plugin_name: plugin_info
for plugin_name, plugin_info in get_plugin('inspect').get_all_plugins().output.items()
for plugin_name, plugin_info in _get_inspect_plugin().get_all_plugins().output.items()
if plugin_name in manifests
}
@ -19,17 +26,17 @@ def get_all_backends():
manifests = {mf.component_name for mf in get_manifests(Backend)}
return {
backend_name: backend_info
for backend_name, backend_info in get_plugin('inspect').get_all_backends().output.items()
for backend_name, backend_info in _get_inspect_plugin().get_all_backends().output.items()
if backend_name in manifests
}
def get_all_events():
return get_plugin('inspect').get_all_events().output
return _get_inspect_plugin().get_all_events().output
def get_all_responses():
return get_plugin('inspect').get_all_responses().output
return _get_inspect_plugin().get_all_responses().output
# noinspection DuplicatedCode
@ -100,16 +107,17 @@ Backends
# noinspection DuplicatedCode
def generate_events_doc():
from platypush.message import event as event_module
events_index = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'events.rst')
events_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'platypush', 'events')
all_events = sorted(event for event in get_all_events().keys())
all_events = sorted(event for event in get_all_events().keys() if event)
for event in all_events:
event_file = os.path.join(events_dir, event[len('platypush.message.event.'):] + '.rst')
event_file = os.path.join(events_dir, event + '.rst')
if not os.path.exists(event_file):
header = '``{}``'.format(event)
divider = '=' * len(header)
body = '\n.. automodule:: {}\n :members:\n'.format(event)
body = '\n.. automodule:: {}.{}\n :members:\n'.format(event_module.__name__, event)
out = '\n'.join([header, divider, body])
with open(event_file, 'w') as f:
@ -127,21 +135,22 @@ Events
''')
for event in all_events:
f.write(' platypush/events/' + event[len('platypush.message.event.'):] + '.rst\n')
f.write(' platypush/events/' + event + '.rst\n')
# noinspection DuplicatedCode
def generate_responses_doc():
from platypush.message import response as response_module
responses_index = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'responses.rst')
responses_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'platypush', 'responses')
all_responses = sorted(response for response in get_all_responses().keys())
all_responses = sorted(response for response in get_all_responses().keys() if response)
for response in all_responses:
response_file = os.path.join(responses_dir, response[len('platypush.message.response.'):] + '.rst')
response_file = os.path.join(responses_dir, response + '.rst')
if not os.path.exists(response_file):
header = '``{}``'.format(response)
divider = '=' * len(header)
body = '\n.. automodule:: {}\n :members:\n'.format(response)
body = '\n.. automodule:: {}.{}\n :members:\n'.format(response_module.__name__, response)
out = '\n'.join([header, divider, body])
with open(response_file, 'w') as f:
@ -159,7 +168,7 @@ Responses
''')
for response in all_responses:
f.write(' platypush/responses/' + response[len('platypush.message.response.'):] + '.rst\n')
f.write(' platypush/responses/' + response + '.rst\n')
generate_plugins_doc()