Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
29 of 77 tasks
bmxp opened this issue Apr 23, 2021 · 22 comments
Open
29 of 77 tasks

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

bmxp opened this issue Apr 23, 2021 · 22 comments
Milestone
Version 1.10

Comments

@bmxp
Copy link
Member

bmxp commented Apr 23, 2021 •
edited by onkelandy

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
Copy link
Contributor

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
Copy link
Member

msinn commented Apr 24, 2021

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.

@msinn msinn changed the title Update Plugin Documentation: Readme.md --> user_doc.rst All plugins: Updatep plugin documentation: readme.md --> user_doc.rst Dec 23, 2021
@bmxp bmxp changed the title All plugins: Updatep plugin documentation: readme.md --> user_doc.rst All plugins: Update plugin documentation: readme.md --> user_doc.rst Mar 10, 2022
@Morg42
Copy link
Member

Morg42 commented Mar 9, 2023 •
edited by aschwith

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
Copy link
Member Author

bmxp commented Mar 9, 2023

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

@msinn
Copy link
Member

msinn commented Mar 9, 2023

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 msinn added this to the Version 1.10 milestone Mar 9, 2023
@msinn
Copy link
Member

msinn commented Aug 29, 2023 •
edited

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
Copy link
Member Author

bmxp commented Aug 29, 2023

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
Copy link
Member

Morg42 commented Aug 29, 2023

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
Copy link
Member Author

bmxp commented Aug 29, 2023 •
edited

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

@msinn
Copy link
Member

msinn commented Aug 29, 2023

Ist der Hinweis inder Doku nicht ausreichend?

@bmxp
Copy link
Member Author

bmxp commented Aug 29, 2023

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

@msinn
Copy link
Member

msinn commented Aug 29, 2023 •
edited

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
Copy link
Member

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
Copy link
Member

msinn commented Aug 29, 2023 •
edited

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
Copy link
Member Author

bmxp commented Aug 29, 2023

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
Copy link
Member

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
Copy link
Member Author

bmxp commented Aug 29, 2023

ok, dann spare ich mir das ;-)

@onkelandy
Copy link
Member

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
Copy link
Member

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
Copy link
Member Author

bmxp commented Sep 22, 2023

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
Copy link
Member

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
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
Version 1.10
Development

No branches or pull requests
5 participants
@msinn @bmxp @onkelandy @aschwith @Morg42