search

smarthomeNG / plugins

Plugins for SmartHomeNG - The device integration platform for your smart home
https://www.smarthomeNG.de
44 stars 101 forks source link

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

Open bmxp opened 3 years ago

bmxp commented 3 years ago

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:

aschwith commented 3 years ago

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 commented 3 years ago

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 commented 1 year ago

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

bmxp commented 1 year ago

We should exclude deprecated plugins from the need of translation an conversion, see https://github.com/smarthomeNG/smarthome/issues/230

msinn commented 1 year ago

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 commented 10 months ago

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 commented 10 months ago

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 commented 10 months ago

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 commented 10 months ago

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

msinn commented 10 months ago

Ist der Hinweis inder Doku nicht ausreichend?

bmxp commented 10 months ago

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

msinn commented 10 months ago

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 commented 10 months ago

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 commented 10 months ago

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.

bmxp commented 10 months ago

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 commented 10 months ago

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 commented 10 months ago

ok, dann spare ich mir das ;-)

onkelandy commented 9 months ago

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 commented 9 months ago

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

bmxp commented 9 months ago

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 commented 9 months ago

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 commented 8 months ago

Ich hab bezüglich Logging hier ein Update erstellt: https://github.com/smarthomeNG/smarthome/pull/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.