[Admin 6] Different links to documentation - Githubissues

ioBroker / ioBroker.admin

user interface for configuration and administration

https://iobroker.net

MIT License

273 stars 78 forks source link

[Admin 6] Different links to documentation #1600

Open klein0r opened 2 years ago

klein0r commented 2 years ago

Describe the bug

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

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

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

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

mcm1957 commented 2 years ago

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