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

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

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