ioBroker.admin icon indicating copy to clipboard operation
ioBroker.admin copied to clipboard

[Admin 6] Different links to documentation

Open klein0r opened this issue 3 years ago • 1 comments

Describe the bug

At the moment there are three (?) ways to open a documentation for an adapter:

  1. In the adapter list by using the ? Button

https://github.com/ioBroker/ioBroker.admin/blob/bbcc2fb28ad21f2550a0bb558005d6c2a631aebc/src-rx/src/tabs/Adapters.jsx#L1000-L1002

https://github.com/ioBroker/ioBroker.admin/blob/bbcc2fb28ad21f2550a0bb558005d6c2a631aebc/src-rx/src/tabs/Adapters.jsx#L1613-L1629

This opens / renders the readme directly in the admin interface. Source of this documentation is iobroker.net

https://github.com/ioBroker/ioBroker.admin/blob/bbcc2fb28ad21f2550a0bb558005d6c2a631aebc/src-rx/src/dialogs/AdapterInfoDialog.jsx#L39


  1. In the instance configuration (jsonConfig)

https://github.com/ioBroker/ioBroker.admin/blob/bbcc2fb28ad21f2550a0bb558005d6c2a631aebc/src-rx/src/tabs/Config.jsx#L208-L226

This opens a new tab to iobroker.net

https://www.iobroker.net/#${lang}/adapters/adapterref/iobroker.${this.props.adapter}/README.md

This is NOT working, if the adapter is not in the official repository


  1. In the instance configuration (materialize / index_m.html)

https://github.com/ioBroker/ioBroker.admin/blob/bbcc2fb28ad21f2550a0bb558005d6c2a631aebc/src-rx/public/js/adapter-settings.js#L589-L593

This opens a new tab to the common.readme property in io-package.json

Summary

  • common.readme is not used when using jsonConfig
  • Some links render the help directly in the admin interface, others lead to external resources
  • common.docs is ignored completely (just used by ioBroker.docs to collect the documentation

Suggestion

  • Do not load resources from iobroker.net (not every adapter is in that repository)
  • Use common.docs to generate links to the documentation / render docs
  • Implement fallback to iobroker.readme if common.docs is not defined

Versions

  • Adapter version: 6.2.3

klein0r avatar Jul 22 '22 10:07 klein0r

I would prefer a clear structure from which locations data is retrieved too. In addition I would like to be able to link the adapter to an (optional) documention provided i.e. via github. (For the meoment I added a rudimentary docu directly into README.md5 but this is not the right place for longer docus I assume.)

mcm1957 avatar Jul 22 '22 16:07 mcm1957