diff --git a/docs/source/backends.rst b/docs/source/backends.rst index 4ed17d68..db27c7f7 100644 --- a/docs/source/backends.rst +++ b/docs/source/backends.rst @@ -1,3 +1,4 @@ + Backends ======== @@ -5,45 +6,48 @@ Backends :maxdepth: 2 :caption: Backends: - platypush/backend.rst - platypush/backend/adafruit.io.rst - platypush/backend/assistant.google.rst - platypush/backend/assistant.snowboy.rst - platypush/backend/bluetooth.fileserver.rst - platypush/backend/bluetooth.pushserver.rst - platypush/backend/button.flic.rst - platypush/backend/camera.pi.rst - platypush/backend/camera.rst - platypush/backend/google.fit.rst - platypush/backend/gps.rst - platypush/backend/http.poll.rst - platypush/backend/http.request.rss.rst - platypush/backend/http.rst - platypush/backend/inotify.rst - platypush/backend/joystick.rst - platypush/backend/kafka.rst - platypush/backend/light.hue.rst - platypush/backend/midi.rst - platypush/backend/mqtt.rst - platypush/backend/music.mopidy.rst - platypush/backend/music.mpd.rst - platypush/backend/music.snapcast.rst - platypush/backend/nfc.rst - platypush/backend/nodered.rst - platypush/backend/pushbullet.rst - platypush/backend/redis.rst - platypush/backend/scard.rst - platypush/backend/sensor.accelerometer.rst - platypush/backend/sensor.bme280.rst - platypush/backend/sensor.distance.vl53l1x.rst - platypush/backend/sensor.envirophat.rst - platypush/backend/sensor.ir.zeroborg.rst - platypush/backend/sensor.leap.rst - platypush/backend/sensor.ltr559.rst - platypush/backend/sensor.mcp3008.rst - platypush/backend/sensor.rst - platypush/backend/sensor.serial.rst - platypush/backend/tcp.rst - platypush/backend/weather.forecast.rst - platypush/backend/websocket.rst - platypush/backend/wiimote.rst + platypush/backends/adafruit.io.rst + platypush/backends/assistant.google.rst + platypush/backends/assistant.snowboy.rst + platypush/backends/bluetooth.rst + platypush/backends/bluetooth.fileserver.rst + platypush/backends/bluetooth.pushserver.rst + platypush/backends/button.flic.rst + platypush/backends/camera.pi.rst + platypush/backends/google.fit.rst + platypush/backends/google.pubsub.rst + platypush/backends/gps.rst + platypush/backends/http.rst + platypush/backends/http.poll.rst + platypush/backends/inotify.rst + platypush/backends/joystick.rst + platypush/backends/kafka.rst + platypush/backends/light.hue.rst + platypush/backends/local.rst + platypush/backends/midi.rst + platypush/backends/mqtt.rst + platypush/backends/music.mopidy.rst + platypush/backends/music.mpd.rst + platypush/backends/music.snapcast.rst + platypush/backends/nfc.rst + platypush/backends/nodered.rst + platypush/backends/ping.rst + platypush/backends/pushbullet.rst + platypush/backends/redis.rst + platypush/backends/scard.rst + platypush/backends/sensor.rst + platypush/backends/sensor.accelerometer.rst + platypush/backends/sensor.bme280.rst + platypush/backends/sensor.distance.rst + platypush/backends/sensor.distance.vl53l1x.rst + platypush/backends/sensor.envirophat.rst + platypush/backends/sensor.ir.zeroborg.rst + platypush/backends/sensor.ltr559.rst + platypush/backends/sensor.mcp3008.rst + platypush/backends/sensor.motion.pwm3901.rst + platypush/backends/sensor.serial.rst + platypush/backends/tcp.rst + platypush/backends/todoist.rst + platypush/backends/weather.forecast.rst + platypush/backends/websocket.rst + platypush/backends/wiimote.rst diff --git a/docs/source/platypush/backend/bluetooth.rst b/docs/source/platypush/backend/bluetooth.rst new file mode 100644 index 00000000..3e75822c --- /dev/null +++ b/docs/source/platypush/backend/bluetooth.rst @@ -0,0 +1,5 @@ +``platypush.backend.bluetooth`` +=============================== + +.. automodule:: platypush.backend.bluetooth + :members: diff --git a/docs/source/platypush/backend/google.pubsub.rst b/docs/source/platypush/backend/google.pubsub.rst new file mode 100644 index 00000000..5f39cf24 --- /dev/null +++ b/docs/source/platypush/backend/google.pubsub.rst @@ -0,0 +1,5 @@ +``platypush.backend.google.pubsub`` +=================================== + +.. automodule:: platypush.backend.google.pubsub + :members: diff --git a/docs/source/platypush/backend/local.rst b/docs/source/platypush/backend/local.rst new file mode 100644 index 00000000..8ed9929e --- /dev/null +++ b/docs/source/platypush/backend/local.rst @@ -0,0 +1,5 @@ +``platypush.backend.local`` +=========================== + +.. automodule:: platypush.backend.local + :members: diff --git a/docs/source/platypush/backend/ping.rst b/docs/source/platypush/backend/ping.rst new file mode 100644 index 00000000..8e643d97 --- /dev/null +++ b/docs/source/platypush/backend/ping.rst @@ -0,0 +1,5 @@ +``platypush.backend.ping`` +========================== + +.. automodule:: platypush.backend.ping + :members: diff --git a/docs/source/platypush/backend/sensor.distance.rst b/docs/source/platypush/backend/sensor.distance.rst new file mode 100644 index 00000000..befe8bdc --- /dev/null +++ b/docs/source/platypush/backend/sensor.distance.rst @@ -0,0 +1,5 @@ +``platypush.backend.sensor.distance`` +===================================== + +.. automodule:: platypush.backend.sensor.distance + :members: diff --git a/docs/source/platypush/backend/sensor.motion.pwm3901.rst b/docs/source/platypush/backend/sensor.motion.pwm3901.rst new file mode 100644 index 00000000..8c596075 --- /dev/null +++ b/docs/source/platypush/backend/sensor.motion.pwm3901.rst @@ -0,0 +1,5 @@ +``platypush.backend.sensor.motion.pwm3901`` +=========================================== + +.. automodule:: platypush.backend.sensor.motion.pwm3901 + :members: diff --git a/docs/source/platypush/backend/todoist.rst b/docs/source/platypush/backend/todoist.rst new file mode 100644 index 00000000..83abf592 --- /dev/null +++ b/docs/source/platypush/backend/todoist.rst @@ -0,0 +1,5 @@ +``platypush.backend.todoist`` +============================= + +.. automodule:: platypush.backend.todoist + :members: diff --git a/docs/source/platypush/plugins/assistant.rst b/docs/source/platypush/plugins/assistant.rst new file mode 100644 index 00000000..4985a3e1 --- /dev/null +++ b/docs/source/platypush/plugins/assistant.rst @@ -0,0 +1,5 @@ +``platypush.plugins.assistant`` +=============================== + +.. automodule:: platypush.plugins.assistant + :members: diff --git a/docs/source/platypush/plugins/camera.android.ipcam.rst b/docs/source/platypush/plugins/camera.android.ipcam.rst new file mode 100644 index 00000000..17af9d97 --- /dev/null +++ b/docs/source/platypush/plugins/camera.android.ipcam.rst @@ -0,0 +1,5 @@ +``platypush.plugins.camera.android.ipcam`` +========================================== + +.. automodule:: platypush.plugins.camera.android.ipcam + :members: diff --git a/docs/source/platypush/plugins/google.pubsub.rst b/docs/source/platypush/plugins/google.pubsub.rst new file mode 100644 index 00000000..6d9fc47d --- /dev/null +++ b/docs/source/platypush/plugins/google.pubsub.rst @@ -0,0 +1,5 @@ +``platypush.plugins.google.pubsub`` +=================================== + +.. automodule:: platypush.plugins.google.pubsub + :members: diff --git a/docs/source/platypush/plugins/http.request.ota.booking.rst b/docs/source/platypush/plugins/http.request.ota.booking.rst new file mode 100644 index 00000000..ccc02b03 --- /dev/null +++ b/docs/source/platypush/plugins/http.request.ota.booking.rst @@ -0,0 +1,5 @@ +``platypush.plugins.http.request.ota.booking`` +============================================== + +.. automodule:: platypush.plugins.http.request.ota.booking + :members: diff --git a/docs/source/platypush/plugins/lastfm.rst b/docs/source/platypush/plugins/lastfm.rst new file mode 100644 index 00000000..49d8b129 --- /dev/null +++ b/docs/source/platypush/plugins/lastfm.rst @@ -0,0 +1,5 @@ +``platypush.plugins.lastfm`` +============================ + +.. automodule:: platypush.plugins.lastfm + :members: diff --git a/docs/source/platypush/plugins/logger.rst b/docs/source/platypush/plugins/logger.rst new file mode 100644 index 00000000..38f1a904 --- /dev/null +++ b/docs/source/platypush/plugins/logger.rst @@ -0,0 +1,5 @@ +``platypush.plugins.logger`` +============================ + +.. automodule:: platypush.plugins.logger + :members: diff --git a/docs/source/platypush/plugins/media.chromecast.rst b/docs/source/platypush/plugins/media.chromecast.rst new file mode 100644 index 00000000..35c70790 --- /dev/null +++ b/docs/source/platypush/plugins/media.chromecast.rst @@ -0,0 +1,5 @@ +``platypush.plugins.media.chromecast`` +====================================== + +.. automodule:: platypush.plugins.media.chromecast + :members: diff --git a/docs/source/platypush/plugins/media.ctrl.rst b/docs/source/platypush/plugins/media.ctrl.rst new file mode 100644 index 00000000..eff5b259 --- /dev/null +++ b/docs/source/platypush/plugins/media.ctrl.rst @@ -0,0 +1,5 @@ +``platypush.plugins.media.ctrl`` +================================ + +.. automodule:: platypush.plugins.media.ctrl + :members: diff --git a/docs/source/platypush/plugins/media.rst b/docs/source/platypush/plugins/media.rst new file mode 100644 index 00000000..14b898cc --- /dev/null +++ b/docs/source/platypush/plugins/media.rst @@ -0,0 +1,5 @@ +``platypush.plugins.media`` +=========================== + +.. automodule:: platypush.plugins.media + :members: diff --git a/docs/source/platypush/plugins/music.rst b/docs/source/platypush/plugins/music.rst new file mode 100644 index 00000000..7354f844 --- /dev/null +++ b/docs/source/platypush/plugins/music.rst @@ -0,0 +1,5 @@ +``platypush.plugins.music`` +=========================== + +.. automodule:: platypush.plugins.music + :members: diff --git a/docs/source/platypush/plugins/ping.rst b/docs/source/platypush/plugins/ping.rst new file mode 100644 index 00000000..48e789c9 --- /dev/null +++ b/docs/source/platypush/plugins/ping.rst @@ -0,0 +1,5 @@ +``platypush.plugins.ping`` +========================== + +.. automodule:: platypush.plugins.ping + :members: diff --git a/docs/source/platypush/plugins/todoist.rst b/docs/source/platypush/plugins/todoist.rst new file mode 100644 index 00000000..bfd121c6 --- /dev/null +++ b/docs/source/platypush/plugins/todoist.rst @@ -0,0 +1,5 @@ +``platypush.plugins.todoist`` +============================= + +.. automodule:: platypush.plugins.todoist + :members: diff --git a/docs/source/platypush/plugins/trello.rst b/docs/source/platypush/plugins/trello.rst new file mode 100644 index 00000000..5b9c49e8 --- /dev/null +++ b/docs/source/platypush/plugins/trello.rst @@ -0,0 +1,5 @@ +``platypush.plugins.trello`` +============================ + +.. automodule:: platypush.plugins.trello + :members: diff --git a/docs/source/platypush/plugins/video.torrentcast.rst b/docs/source/platypush/plugins/video.torrentcast.rst new file mode 100644 index 00000000..0ae355f2 --- /dev/null +++ b/docs/source/platypush/plugins/video.torrentcast.rst @@ -0,0 +1,5 @@ +``platypush.plugins.video.torrentcast`` +======================================= + +.. automodule:: platypush.plugins.video.torrentcast + :members: diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index bd5910ba..75057237 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -1,3 +1,4 @@ + Plugins ======= @@ -6,29 +7,32 @@ Plugins :caption: Plugins: platypush/plugins/adafruit.io.rst + platypush/plugins/assistant.rst platypush/plugins/assistant.echo.rst - platypush/plugins/assistant.google.pushtotalk.rst platypush/plugins/assistant.google.rst + platypush/plugins/assistant.google.pushtotalk.rst platypush/plugins/autoremote.rst platypush/plugins/bluetooth.rst platypush/plugins/bluetooth.ble.rst - platypush/plugins/calendar.ical.rst platypush/plugins/calendar.rst + platypush/plugins/calendar.ical.rst + platypush/plugins/camera.rst + platypush/plugins/camera.android.ipcam.rst platypush/plugins/camera.ir.mlx90640.rst platypush/plugins/camera.pi.rst - platypush/plugins/camera.rst platypush/plugins/clipboard.rst platypush/plugins/db.rst platypush/plugins/dropbox.rst platypush/plugins/file.rst + platypush/plugins/google.rst platypush/plugins/google.calendar.rst - platypush/plugins/google.credentials.rst platypush/plugins/google.fit.rst platypush/plugins/google.mail.rst platypush/plugins/google.maps.rst - platypush/plugins/google.rst + platypush/plugins/google.pubsub.rst platypush/plugins/google.youtube.rst platypush/plugins/gpio.rst + platypush/plugins/gpio.sensor.rst platypush/plugins/gpio.sensor.accelerometer.rst platypush/plugins/gpio.sensor.bme280.rst platypush/plugins/gpio.sensor.distance.rst @@ -37,25 +41,27 @@ Plugins platypush/plugins/gpio.sensor.ltr559.rst platypush/plugins/gpio.sensor.mcp3008.rst platypush/plugins/gpio.sensor.motion.pwm3901.rst - platypush/plugins/gpio.sensor.rst platypush/plugins/gpio.zeroborg.rst platypush/plugins/homeseer.rst - platypush/plugins/http.request.rss.rst platypush/plugins/http.request.rst + platypush/plugins/http.request.ota.booking.rst + platypush/plugins/http.request.rss.rst platypush/plugins/http.webpage.rst platypush/plugins/ifttt.rst platypush/plugins/inspect.rst platypush/plugins/kafka.rst - platypush/plugins/light.hue.rst + platypush/plugins/lastfm.rst platypush/plugins/light.rst + platypush/plugins/light.hue.rst + platypush/plugins/logger.rst + platypush/plugins/media.rst + platypush/plugins/media.chromecast.rst + platypush/plugins/media.ctrl.rst platypush/plugins/media.kodi.rst platypush/plugins/media.mplayer.rst platypush/plugins/media.mpv.rst platypush/plugins/media.omxplayer.rst platypush/plugins/media.plex.rst - platypush/plugins/media.search.local.rst - platypush/plugins/media.search.torrent.rst - platypush/plugins/media.search.youtube.rst platypush/plugins/media.subtitles.rst platypush/plugins/media.vlc.rst platypush/plugins/media.webtorrent.rst @@ -63,8 +69,10 @@ Plugins platypush/plugins/ml.cv.rst platypush/plugins/mobile.join.rst platypush/plugins/mqtt.rst + platypush/plugins/music.rst platypush/plugins/music.mpd.rst platypush/plugins/music.snapcast.rst + platypush/plugins/ping.rst platypush/plugins/pushbullet.rst platypush/plugins/redis.rst platypush/plugins/serial.rst @@ -72,14 +80,16 @@ Plugins platypush/plugins/sound.rst platypush/plugins/switch.rst platypush/plugins/switch.switchbot.rst - platypush/plugins/switch.tplink.rst platypush/plugins/switch.wemo.rst + platypush/plugins/todoist.rst platypush/plugins/torrent.rst - platypush/plugins/tts.google.rst + platypush/plugins/trello.rst platypush/plugins/tts.rst + platypush/plugins/tts.google.rst platypush/plugins/user.rst platypush/plugins/utils.rst platypush/plugins/variable.rst + platypush/plugins/video.torrentcast.rst platypush/plugins/weather.forecast.rst platypush/plugins/websocket.rst platypush/plugins/wiimote.rst diff --git a/generate_missing_docs.py b/generate_missing_docs.py new file mode 100644 index 00000000..67f84e87 --- /dev/null +++ b/generate_missing_docs.py @@ -0,0 +1,84 @@ +import os + +from platypush.context import get_plugin + + +def get_all_plugins(): + return get_plugin('inspect').get_all_plugins().output + + +def get_all_backends(): + return get_plugin('inspect').get_all_backends().output + + +# noinspection DuplicatedCode +def generate_plugins_doc(): + plugins_index = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'plugins.rst') + plugins_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'platypush', 'plugins') + all_plugins = sorted(plugin for plugin in get_all_plugins().keys()) + + for plugin in all_plugins: + plugin_file = os.path.join(plugins_dir, plugin + '.rst') + if not os.path.exists(plugin_file): + plugin = 'platypush.plugins.' + plugin + header = '``{}``'.format(plugin) + divider = '=' * len(header) + body = '\n.. automodule:: {}\n :members:\n'.format(plugin) + out = '\n'.join([header, divider, body]) + + with open(plugin_file, 'w') as f: + f.write(out) + + with open(plugins_index, 'w') as f: + f.write(''' +Plugins +======= + +.. toctree:: + :maxdepth: 2 + :caption: Plugins: + +''') + + for plugin in all_plugins: + f.write(' platypush/plugins/' + plugin + '.rst\n') + + +# noinspection DuplicatedCode +def generate_backends_doc(): + backends_index = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'backends.rst') + backends_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'platypush', 'backend') + all_backends = sorted(backend for backend in get_all_backends().keys()) + + for backend in all_backends: + backend_file = os.path.join(backends_dir, backend + '.rst') + if not os.path.exists(backend_file): + backend = 'platypush.backend.' + backend + header = '``{}``'.format(backend) + divider = '=' * len(header) + body = '\n.. automodule:: {}\n :members:\n'.format(backend) + out = '\n'.join([header, divider, body]) + + with open(backend_file, 'w') as f: + f.write(out) + + with open(backends_index, 'w') as f: + f.write(''' +Backends +======== + +.. toctree:: + :maxdepth: 2 + :caption: Backends: + +''') + + for backend in all_backends: + f.write(' platypush/backends/' + backend + '.rst\n') + + +generate_plugins_doc() +generate_backends_doc() + + +# vim:sw=4:ts=4:et: diff --git a/generate_missing_docs.sh b/generate_missing_docs.sh deleted file mode 100755 index bb4c755c..00000000 --- a/generate_missing_docs.sh +++ /dev/null @@ -1,60 +0,0 @@ -#!/bin/bash - -latest_docs_commit=$(git log ./docs | head -1 | cut -d' ' -f 2) -code_dirs='platypush/plugins platypush/backend platypush/message/event' -target_dir='docs/source/platypush' - -git diff --name-status $latest_docs_commit..HEAD $code_dirs \ - | grep '^A' | grep '\.py$' | awk '{print $2}' | while read filename; do - - module_name=$(echo -n $filename | sed -r -e 's/(.*)\.py$/\1/' | tr '/' '.') - - case $filename in - platypush/backend/*) - target_file="$target_dir/backend/$(echo -n $filename | sed -r -e 's/^platypush\/backend\/(.*)\.py$/\1.rst/' | tr '/' '.')" - ;; - platypush/plugins/*) - target_file="$target_dir/plugins/$(echo -n $filename | sed -r -e 's/^platypush\/plugins\/(.*)\.py$/\1.rst/' | tr '/' '.')" - ;; - platypush/message/event/*) - target_file="$target_dir/events/$(echo -n $filename | sed -r -e 's/^platypush\/message\/event\/(.*)\.py$/\1.rst/' | tr '/' '.')" - ;; - esac - - backticks='``' - header_top="$backticks$module_name$backticks" - echo "$header_top" > "$target_file" - perl -e "print '=' x length('$header_top')" >> "$target_file" - echo >> "$target_file" - echo >> "$target_file" - echo ".. automodule:: $module_name" >> "$target_file" - echo -e "\t:members:" >> $target_file - echo >> "$target_file" - - case $filename in - platypush/backend/*) - index_file="$target_dir/../backends.rst" - header=$(cat $index_file | head -8) - files=$(find docs/source/platypush/backend -type f -name '*.rst' | sort | sed -r -e 's/^docs\/source\/(.*)$/ \1/') - echo $"$header" > $index_file - echo $"$files" >> $index_file - ;; - platypush/plugins/*) - index_file="$target_dir/../plugins.rst" - header=$(cat $index_file | head -7) - files=$(find docs/source/platypush/plugins -type f -name '*.rst' | sort | sed -r -e 's/^docs\/source\/(.*)$/ \1/') - echo $"$header" > $index_file - echo >> $index_file - echo $"$files" >> $index_file - ;; - platypush/message/event/*) - index_file="$target_dir/../events.rst" - header=$(cat $index_file | head -7) - files=$(find docs/source/platypush/events -type f -name '*.rst' | sort | sed -r -e 's/^docs\/source\/(.*)$/ \1/') - echo $"$header" > $index_file - echo >> $index_file - echo $"$files" >> $index_file - ;; - esac -done - diff --git a/platypush/plugins/inspect.py b/platypush/plugins/inspect.py index b539f872..ccf4d03d 100644 --- a/platypush/plugins/inspect.py +++ b/platypush/plugins/inspect.py @@ -5,8 +5,10 @@ import pkgutil import re import threading +import platypush.backend import platypush.plugins +from platypush.backend import Backend from platypush.plugins import Plugin, action from platypush.utils import get_decorators @@ -30,6 +32,17 @@ class Model: return docutils.core.publish_parts(doc, writer_name='html')['html_body'] +class BackendModel(Model): + def __init__(self, backend, prefix='', html_doc: bool = False): + self.name = backend.__module__[len(prefix):] + self.html_doc = html_doc + self.doc = self.to_html(backend.__doc__) if html_doc and backend.__doc__ else backend.__doc__ + + def __iter__(self): + for attr in ['name', 'doc', 'html_doc']: + yield attr, getattr(self, attr) + + class PluginModel(Model): def __init__(self, plugin, prefix='', html_doc: bool = False): self.name = plugin.__module__[len(prefix):] @@ -119,7 +132,9 @@ class InspectPlugin(Plugin): def __init__(self, **kwargs): super().__init__(**kwargs) self._plugins = {} + self._backends = {} self._plugins_lock = threading.RLock() + self._backends_lock = threading.RLock() self._html_doc = False def _init_plugins(self): @@ -141,6 +156,25 @@ class InspectPlugin(Plugin): if model.name: self._plugins[model.name] = model + def _init_backends(self): + package = platypush.backend + prefix = package.__name__ + '.' + + for _, modname, _ in pkgutil.walk_packages(path=package.__path__, + prefix=prefix, + onerror=lambda x: None): + # noinspection PyBroadException + try: + module = importlib.import_module(modname) + except: + continue + + for _, obj in inspect.getmembers(module): + if inspect.isclass(obj) and issubclass(obj, Backend): + model = BackendModel(backend=obj, prefix=prefix, html_doc=self._html_doc) + if model.name: + self._backends[model.name] = model + @action def get_all_plugins(self, html_doc: bool = None): """ @@ -156,5 +190,20 @@ class InspectPlugin(Plugin): for name, plugin in self._plugins.items() }) + @action + def get_all_backends(self, html_doc: bool = None): + """ + :param html_doc: If True then the docstring will be parsed into HTML (default: False) + """ + with self._backends_lock: + if not self._backends or (html_doc is not None and html_doc != self._html_doc): + self._html_doc = html_doc + self._init_backends() + + return json.dumps({ + name: dict(backend) + for name, backend in self._backends.items() + }) + # vim:sw=4:ts=4:et: