Generated missing docs

This commit is contained in:
Fabio Manganiello 2019-12-30 10:16:55 +01:00
parent bc7c248f72
commit 9d961a265f
26 changed files with 307 additions and 115 deletions

View file

@ -1,3 +1,4 @@
Backends Backends
======== ========
@ -5,45 +6,48 @@ Backends
:maxdepth: 2 :maxdepth: 2
:caption: Backends: :caption: Backends:
platypush/backend.rst platypush/backends/adafruit.io.rst
platypush/backend/adafruit.io.rst platypush/backends/assistant.google.rst
platypush/backend/assistant.google.rst platypush/backends/assistant.snowboy.rst
platypush/backend/assistant.snowboy.rst platypush/backends/bluetooth.rst
platypush/backend/bluetooth.fileserver.rst platypush/backends/bluetooth.fileserver.rst
platypush/backend/bluetooth.pushserver.rst platypush/backends/bluetooth.pushserver.rst
platypush/backend/button.flic.rst platypush/backends/button.flic.rst
platypush/backend/camera.pi.rst platypush/backends/camera.pi.rst
platypush/backend/camera.rst platypush/backends/google.fit.rst
platypush/backend/google.fit.rst platypush/backends/google.pubsub.rst
platypush/backend/gps.rst platypush/backends/gps.rst
platypush/backend/http.poll.rst platypush/backends/http.rst
platypush/backend/http.request.rss.rst platypush/backends/http.poll.rst
platypush/backend/http.rst platypush/backends/inotify.rst
platypush/backend/inotify.rst platypush/backends/joystick.rst
platypush/backend/joystick.rst platypush/backends/kafka.rst
platypush/backend/kafka.rst platypush/backends/light.hue.rst
platypush/backend/light.hue.rst platypush/backends/local.rst
platypush/backend/midi.rst platypush/backends/midi.rst
platypush/backend/mqtt.rst platypush/backends/mqtt.rst
platypush/backend/music.mopidy.rst platypush/backends/music.mopidy.rst
platypush/backend/music.mpd.rst platypush/backends/music.mpd.rst
platypush/backend/music.snapcast.rst platypush/backends/music.snapcast.rst
platypush/backend/nfc.rst platypush/backends/nfc.rst
platypush/backend/nodered.rst platypush/backends/nodered.rst
platypush/backend/pushbullet.rst platypush/backends/ping.rst
platypush/backend/redis.rst platypush/backends/pushbullet.rst
platypush/backend/scard.rst platypush/backends/redis.rst
platypush/backend/sensor.accelerometer.rst platypush/backends/scard.rst
platypush/backend/sensor.bme280.rst platypush/backends/sensor.rst
platypush/backend/sensor.distance.vl53l1x.rst platypush/backends/sensor.accelerometer.rst
platypush/backend/sensor.envirophat.rst platypush/backends/sensor.bme280.rst
platypush/backend/sensor.ir.zeroborg.rst platypush/backends/sensor.distance.rst
platypush/backend/sensor.leap.rst platypush/backends/sensor.distance.vl53l1x.rst
platypush/backend/sensor.ltr559.rst platypush/backends/sensor.envirophat.rst
platypush/backend/sensor.mcp3008.rst platypush/backends/sensor.ir.zeroborg.rst
platypush/backend/sensor.rst platypush/backends/sensor.ltr559.rst
platypush/backend/sensor.serial.rst platypush/backends/sensor.mcp3008.rst
platypush/backend/tcp.rst platypush/backends/sensor.motion.pwm3901.rst
platypush/backend/weather.forecast.rst platypush/backends/sensor.serial.rst
platypush/backend/websocket.rst platypush/backends/tcp.rst
platypush/backend/wiimote.rst platypush/backends/todoist.rst
platypush/backends/weather.forecast.rst
platypush/backends/websocket.rst
platypush/backends/wiimote.rst

View file

@ -0,0 +1,5 @@
``platypush.backend.bluetooth``
===============================
.. automodule:: platypush.backend.bluetooth
:members:

View file

@ -0,0 +1,5 @@
``platypush.backend.google.pubsub``
===================================
.. automodule:: platypush.backend.google.pubsub
:members:

View file

@ -0,0 +1,5 @@
``platypush.backend.local``
===========================
.. automodule:: platypush.backend.local
:members:

View file

@ -0,0 +1,5 @@
``platypush.backend.ping``
==========================
.. automodule:: platypush.backend.ping
:members:

View file

@ -0,0 +1,5 @@
``platypush.backend.sensor.distance``
=====================================
.. automodule:: platypush.backend.sensor.distance
:members:

View file

@ -0,0 +1,5 @@
``platypush.backend.sensor.motion.pwm3901``
===========================================
.. automodule:: platypush.backend.sensor.motion.pwm3901
:members:

View file

@ -0,0 +1,5 @@
``platypush.backend.todoist``
=============================
.. automodule:: platypush.backend.todoist
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.assistant``
===============================
.. automodule:: platypush.plugins.assistant
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.camera.android.ipcam``
==========================================
.. automodule:: platypush.plugins.camera.android.ipcam
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.google.pubsub``
===================================
.. automodule:: platypush.plugins.google.pubsub
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.http.request.ota.booking``
==============================================
.. automodule:: platypush.plugins.http.request.ota.booking
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.lastfm``
============================
.. automodule:: platypush.plugins.lastfm
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.logger``
============================
.. automodule:: platypush.plugins.logger
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.media.chromecast``
======================================
.. automodule:: platypush.plugins.media.chromecast
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.media.ctrl``
================================
.. automodule:: platypush.plugins.media.ctrl
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.media``
===========================
.. automodule:: platypush.plugins.media
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.music``
===========================
.. automodule:: platypush.plugins.music
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.ping``
==========================
.. automodule:: platypush.plugins.ping
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.todoist``
=============================
.. automodule:: platypush.plugins.todoist
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.trello``
============================
.. automodule:: platypush.plugins.trello
:members:

View file

@ -0,0 +1,5 @@
``platypush.plugins.video.torrentcast``
=======================================
.. automodule:: platypush.plugins.video.torrentcast
:members:

View file

@ -1,3 +1,4 @@
Plugins Plugins
======= =======
@ -6,29 +7,32 @@ Plugins
:caption: Plugins: :caption: Plugins:
platypush/plugins/adafruit.io.rst platypush/plugins/adafruit.io.rst
platypush/plugins/assistant.rst
platypush/plugins/assistant.echo.rst platypush/plugins/assistant.echo.rst
platypush/plugins/assistant.google.pushtotalk.rst
platypush/plugins/assistant.google.rst platypush/plugins/assistant.google.rst
platypush/plugins/assistant.google.pushtotalk.rst
platypush/plugins/autoremote.rst platypush/plugins/autoremote.rst
platypush/plugins/bluetooth.rst platypush/plugins/bluetooth.rst
platypush/plugins/bluetooth.ble.rst platypush/plugins/bluetooth.ble.rst
platypush/plugins/calendar.ical.rst
platypush/plugins/calendar.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.ir.mlx90640.rst
platypush/plugins/camera.pi.rst platypush/plugins/camera.pi.rst
platypush/plugins/camera.rst
platypush/plugins/clipboard.rst platypush/plugins/clipboard.rst
platypush/plugins/db.rst platypush/plugins/db.rst
platypush/plugins/dropbox.rst platypush/plugins/dropbox.rst
platypush/plugins/file.rst platypush/plugins/file.rst
platypush/plugins/google.rst
platypush/plugins/google.calendar.rst platypush/plugins/google.calendar.rst
platypush/plugins/google.credentials.rst
platypush/plugins/google.fit.rst platypush/plugins/google.fit.rst
platypush/plugins/google.mail.rst platypush/plugins/google.mail.rst
platypush/plugins/google.maps.rst platypush/plugins/google.maps.rst
platypush/plugins/google.rst platypush/plugins/google.pubsub.rst
platypush/plugins/google.youtube.rst platypush/plugins/google.youtube.rst
platypush/plugins/gpio.rst platypush/plugins/gpio.rst
platypush/plugins/gpio.sensor.rst
platypush/plugins/gpio.sensor.accelerometer.rst platypush/plugins/gpio.sensor.accelerometer.rst
platypush/plugins/gpio.sensor.bme280.rst platypush/plugins/gpio.sensor.bme280.rst
platypush/plugins/gpio.sensor.distance.rst platypush/plugins/gpio.sensor.distance.rst
@ -37,25 +41,27 @@ Plugins
platypush/plugins/gpio.sensor.ltr559.rst platypush/plugins/gpio.sensor.ltr559.rst
platypush/plugins/gpio.sensor.mcp3008.rst platypush/plugins/gpio.sensor.mcp3008.rst
platypush/plugins/gpio.sensor.motion.pwm3901.rst platypush/plugins/gpio.sensor.motion.pwm3901.rst
platypush/plugins/gpio.sensor.rst
platypush/plugins/gpio.zeroborg.rst platypush/plugins/gpio.zeroborg.rst
platypush/plugins/homeseer.rst platypush/plugins/homeseer.rst
platypush/plugins/http.request.rss.rst
platypush/plugins/http.request.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/http.webpage.rst
platypush/plugins/ifttt.rst platypush/plugins/ifttt.rst
platypush/plugins/inspect.rst platypush/plugins/inspect.rst
platypush/plugins/kafka.rst platypush/plugins/kafka.rst
platypush/plugins/light.hue.rst platypush/plugins/lastfm.rst
platypush/plugins/light.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.kodi.rst
platypush/plugins/media.mplayer.rst platypush/plugins/media.mplayer.rst
platypush/plugins/media.mpv.rst platypush/plugins/media.mpv.rst
platypush/plugins/media.omxplayer.rst platypush/plugins/media.omxplayer.rst
platypush/plugins/media.plex.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.subtitles.rst
platypush/plugins/media.vlc.rst platypush/plugins/media.vlc.rst
platypush/plugins/media.webtorrent.rst platypush/plugins/media.webtorrent.rst
@ -63,8 +69,10 @@ Plugins
platypush/plugins/ml.cv.rst platypush/plugins/ml.cv.rst
platypush/plugins/mobile.join.rst platypush/plugins/mobile.join.rst
platypush/plugins/mqtt.rst platypush/plugins/mqtt.rst
platypush/plugins/music.rst
platypush/plugins/music.mpd.rst platypush/plugins/music.mpd.rst
platypush/plugins/music.snapcast.rst platypush/plugins/music.snapcast.rst
platypush/plugins/ping.rst
platypush/plugins/pushbullet.rst platypush/plugins/pushbullet.rst
platypush/plugins/redis.rst platypush/plugins/redis.rst
platypush/plugins/serial.rst platypush/plugins/serial.rst
@ -72,14 +80,16 @@ Plugins
platypush/plugins/sound.rst platypush/plugins/sound.rst
platypush/plugins/switch.rst platypush/plugins/switch.rst
platypush/plugins/switch.switchbot.rst platypush/plugins/switch.switchbot.rst
platypush/plugins/switch.tplink.rst
platypush/plugins/switch.wemo.rst platypush/plugins/switch.wemo.rst
platypush/plugins/todoist.rst
platypush/plugins/torrent.rst platypush/plugins/torrent.rst
platypush/plugins/tts.google.rst platypush/plugins/trello.rst
platypush/plugins/tts.rst platypush/plugins/tts.rst
platypush/plugins/tts.google.rst
platypush/plugins/user.rst platypush/plugins/user.rst
platypush/plugins/utils.rst platypush/plugins/utils.rst
platypush/plugins/variable.rst platypush/plugins/variable.rst
platypush/plugins/video.torrentcast.rst
platypush/plugins/weather.forecast.rst platypush/plugins/weather.forecast.rst
platypush/plugins/websocket.rst platypush/plugins/websocket.rst
platypush/plugins/wiimote.rst platypush/plugins/wiimote.rst

84
generate_missing_docs.py Normal file
View file

@ -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:

View file

@ -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

View file

@ -5,8 +5,10 @@ import pkgutil
import re import re
import threading import threading
import platypush.backend
import platypush.plugins import platypush.plugins
from platypush.backend import Backend
from platypush.plugins import Plugin, action from platypush.plugins import Plugin, action
from platypush.utils import get_decorators from platypush.utils import get_decorators
@ -30,6 +32,17 @@ class Model:
return docutils.core.publish_parts(doc, writer_name='html')['html_body'] 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): class PluginModel(Model):
def __init__(self, plugin, prefix='', html_doc: bool = False): def __init__(self, plugin, prefix='', html_doc: bool = False):
self.name = plugin.__module__[len(prefix):] self.name = plugin.__module__[len(prefix):]
@ -119,7 +132,9 @@ class InspectPlugin(Plugin):
def __init__(self, **kwargs): def __init__(self, **kwargs):
super().__init__(**kwargs) super().__init__(**kwargs)
self._plugins = {} self._plugins = {}
self._backends = {}
self._plugins_lock = threading.RLock() self._plugins_lock = threading.RLock()
self._backends_lock = threading.RLock()
self._html_doc = False self._html_doc = False
def _init_plugins(self): def _init_plugins(self):
@ -141,6 +156,25 @@ class InspectPlugin(Plugin):
if model.name: if model.name:
self._plugins[model.name] = model 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 @action
def get_all_plugins(self, html_doc: bool = None): def get_all_plugins(self, html_doc: bool = None):
""" """
@ -156,5 +190,20 @@ class InspectPlugin(Plugin):
for name, plugin in self._plugins.items() 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: # vim:sw=4:ts=4:et: