All plugins: Update plugin documentation: readme.md --> user_doc.rst

[bmxp]

It would be great to inspect the plugin documentation if there are old readme.md present.
In this case they should be converted from English readme.md which is deprecated to a German user_doc.rst.

---

Copied from the contribution of Morg42 (9. March 2023):

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 -> marked deprecated
• 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 -> retired
• indego
• influxdata -> marked deprecated
• influxdb
• intercom_2n
• join
• jvcproj
• kathrein
• kostal
• kostalmodbus
• ksemmodbus
• logo
• luxtronic2
• mailrcv
• mailsend
• memlog -> marked deprecated
• miflora
• milight
• mlgw
• mvg_live
• nuki
• nut
• odlinfo
• operationlog -> marked deprecated
• plex
• pushbullet
• pushover
• raumfeld -> marked deprecated
• raumfeld_ng
• rcswitch
• robonect
• roomba
• roomba_980
• rrd
• rtr
• russound
• slack
• sma
• sma_em
• smarttv
• sml
• snom -> retired
• sqlite_visu2_8 -> marked deprecated
• systemair
• thz
• traffic
• trovis557x
• unifi
• volkszaehler
• vr100 -> retired
• wettercom
• withings_health
• xmpp
• zwave -> not marked deprecated, but the underlying Python module is not maintained any more

[aschwith]

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?

[msinn]

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.

[Morg42]

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

[bmxp]

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

[msinn]

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

[msinn]

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.

[bmxp]

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?

[Morg42]

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.

[bmxp]

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

[msinn]

Ist der Hinweis inder Doku nicht ausreichend?

[bmxp]

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

[msinn]

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.

[onkelandy]

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)?

[msinn]

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

[bmxp]

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

[onkelandy]

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 ;)

[bmxp]

ok, dann spare ich mir das ;-)

[onkelandy]

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

[onkelandy]

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

[bmxp]

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.

[onkelandy]

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())}

[onkelandy]

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.