All plugins: Update plugin documentation: readme.md --> user_doc.rst about plugins HOT 22 OPEN

Thanks for the corrections in the neato and casambi plugin docs. By the way, how can I locally build the user documentation to check if there are formal errors in those user_doc.rst files?

from plugins.

To build the documentation locally,
you need to install the requirements from doc/requirements.txt to get Sphinx going.
Afterwards simply run build_doc_local.sh from the doc directory.
The completed documentation is put under doc/user/build/html. Just load the index.html in a browser.

from plugins.

The following plugins need to be worked on as they have an existing README but no user_doc.rst:

• alexa -> marked deprecated
• apcups
• appletv
• artnet
• asterisk
• blockly
• bsblan
• buderus
• co2meter
• comfoair
• dashbutton -> not marked deprecated, but dashbuttons are not sold by Amazon any more
• datalog
• deebot_ozmo -> not marked deprecated, but the underlying Python module is not maintained any more
• easymeter -> marked deprecated
• ebus
• ecmd -> marked deprecated
• elro -> marked deprecated
• enigma2
• eta_pu
• harmony
• helios
• homeconnect
• hue
• iaqstick
• indego
• influxdata -> marked deprecated
• influxdb
• intercom_2n
• join
• jvcproj
• kathrein
• kostal
• kostalmodbus
• ksemmodbus
• logo
• luxtronic2
• mailrcv
• mailsend
• memlog
• miflora
• milight
• mlgw
• mvg_live
• nuki
• nut
• odlinfo
• plex
• pushbullet
• pushover
• raumfeld
• raumfeld_ng
• rcswitch
• robonect
• roomba
• roomba_980
• rrd
• rtr
• russound
• slack
• sma
• sma_em
• smarttv
• sml
• snom
• sqlite_visu2_8 -> marked deprecated
• systemair
• thz
• traffic
• trovis557x
• unifi
• volkszaehler
• vr100
• wettercom
• withings_health
• xmpp
• zwave -> not marked deprecated, but the underlying Python module is not maintained any more

from plugins.

We should exclude deprecated plugins from the need of translation an conversion, see smarthomeNG/smarthome#230

from plugins.

I have added deprecated comments and two comments, where the plugin is not deprecated but it might not be worth the effort to update the plugin

from plugins.

I copied Morg's list to the first post (to make the counters visible in the issue list).

The only changes since 9. of march are three plugins that have been retired.

from plugins.

Ich habe mal geschaut aber nirgends eine explizite Anweisung gefunden:

Wenn user_doc.rst erstellt wurde dann readme.md löschen.

Aktuell ist z.B. im DLMS Plugin beides drin und das würde IMHO eigentlich doppelt sein, oder?

from plugins.

Wenn readme.md deprecated ist, könnte man es dann löschen ;)

Die Informationen aus readme.md sollen ja "eingedeutscht" und in RST-Format überführt werden. Wenn also alles in user_doc.rst ist, kann die readme weg.

from plugins.

Dann sollten wir das ggf. auch irgendwo (z.B. hier) so dokumentieren...

from plugins.

Ist der Hinweis inder Doku nicht ausreichend?

from plugins.

Nein, da sollten wir dann schon reinschreiben das die alte Readme.md gelöscht werden soll finde ich

from plugins.

Das war von meinem Verständnis her in "überführen" impliziert.

Kann ich aber gerne noch mal explizit rein schreiben, damit es jeder merkt.

Nachtrag: Für mich besteht das Problem aber vorwiegend darin, dass keine user_doc.rst geschrieben wird und nur in Ausnahmefällen darin, dass die README.md nicht geklöcht wird nachdem alle Informationen übertragen wurden.

from plugins.

Versuchen wirs (nochmals) mit einem Aufruf im Forum? Oder wie wärs wenn wir ChatGPT mal darauf ansetzen (mit File-Uploads oder notfalls Copy-Paste)?

from plugins.

Das mit dem nochmal versuchen wird wohl wenig fruchten. Viele der betrofenen Plugins sind so alt, dass sie keinen richtigen Mainainer mehr haben.

Die Doku umzustellen macht auch am meisten Sinn, wenn an dem jeweiligen Plugin sowieso geschraubt wird.

Ich habe die Hinweise ergänzt.

• in der Kurzanleitung: Plugin Dokumentation
• in der Referenz:Dokumentation des Plugins

from plugins.

Ich kann mir das eine oder andere Plugin noch mal vornehmen.. Asterisk habe ich in der Firma im Einsatz und apcups auch. Beim dlms und smlx schaue ich ob eine readme wegkann...

from plugins.

apcups hab ich mal angefangen gehabt, glaub das user_doc ist fertig, ich schau später nochmals. Bin da irgendwo hängengeblieben.. Geiler Name des Plugins übrigens.. bei mir waren das immer die ap Tassen ;)

from plugins.

ok, dann spare ich mir das ;-)

from plugins.

Sollen wir in dem Zusammenhang mal noch ein bisschen mehr ausmisten..?
Ich denke, gerade operationlog und memlog sind (beinahe?) obsolet. Ist es eurer Meinung nach den Aufwand wert, die Docu entsprechend anzupassen und zu erklären, wie die Funktionen mit Bordmitteln umsetzbar sind..? Oder einfach mal 1:1 README ins user_doc und gut ist..

from plugins.

Das Datalog Plugin ist auch beinahe ersetzbar durch Bordmittel.. Was zB fehlt wären diese "Variablen"

• time - the string representation of the time
• stamp - the unix timestamp of the time

from plugins.

Also wenn man das mit Bordmitteln auch kann dann wäre es ja gut das mal 1:1 nebeneinader darzustellen. Dann können die auf deprecated gesetzt werden und irgendwann ml verschwinden.

from plugins.

Ich hab mir mal das memlog genauer angesehen. Theoretisch ermöglicht es, über Items den Loglevel, Threadname, Zeit und Message anzugeben. De facto funktioniert bei mir aber nur die Message. Der Rest wird im smartvisu widget ohnehin nicht angezeigt. Insofern erschließt sich mir der Rest nicht ganz.
Das Logging aus Logiken habe ich irgendwie nicht hinbekommen, aber auch hier wäre das soweit über logging.yaml problemlos möglich, behaupte ich.

Einziger Benefit so far - man kann den Inhalt der Message über ein Item definieren. Um das abzubilden müsste im aktuellen log_change möglich sein, den Wert aus einem Item auszulesen, also zB

log_text: sh.item_d.property.value

oder vielleicht sogar in Form von {eval(sh.item())}

from plugins.

Ich hab bezüglich Logging hier ein Update erstellt: smarthomeNG/smarthome#605
Werde dann nochmals direkt die drei erwähnten Plugins operationlog, datalog und memlog gegenüber stellen, aber ich denke, somit wären alle Features abgedeckt.

from plugins.