Add documentation for adding a widget icon#41
Add documentation for adding a widget icon#41rutger-seascape wants to merge 5 commits intobluerobotics:latestfrom
Conversation
There was a problem hiding this comment.
Hey Rutger! Thanks a lot for this contribution!
And this API was actually broken recently (during the 1.18 beta phase), as we still didn't had anyone using it (only two internal extensions that were still in beta as well).
The standard changed from snake_case to camelCase, so the new fields are called iframeUrl and iframeIcon. You can find the whole schema in this file of the Cockpit repository.
You can find the discussion about those changes as well as the new features that were added here.
|
Hey @rafaellehmkuhl , Thanks for your answer :). Check, very cool pull request you added, did not know this was in the works. This gives some possibilities for my own extension. Should I also add documentation for the joystick mapping suggestions? |
If you'd like to cover the surrounding feature set, you can document some or all of the undocumented aspects of the external integrations topic :-) |
Feel free to choose how to proceed. If you want to just finish this one with the instructions for the icon and url, which is the basic support, that's fine. If you want to document the whole API, even better! |
|
Thanks for your replies. I will look into covering the whole cockpit_extras.json file. |
…ps to your cockpit_extras endpoint
rutger-seascape
force-pushed
the
feature/auto-iframe-docs
branch
from
e0dbbd4 to
4624200
Compare
|
Hey @rafaellehmkuhl , Could you have a look at my recent changes? I have documented the new cockpit_extras API according to the schema you sent me and I used some other pieces of text/information I found in different Blue Robotics repositories. I think it would be nice to have some screenshots of the joystick mapping suggestions, do you have any at hand by chance? |
Super cool @rutger-seascape! That's a really nice start! I took a look and I will try to wrote down the suggestions till friday. Sorry. for the delay. I usually try to do it in the same day but we are kind of in a rush right now with the stable release. And @ES-Alexander is the responsible for the docs, so I'm sure he will have some suggestions as well! |
|
And here are the images you requested: 
.
|
|
@rutger-seascape I got some spare time and was starting my review but unfortunately there is (again) a Github incident happening right now and I'm not being able to push the comments in the review. Will try again in the next hours. |
ES-Alexander
left a comment
ES-Alexander
left a comment
There was a problem hiding this comment.
Agreed that this is a great start - thanks!
I've given some comments on the high level structure and some missing contextualisation.
Given the "no relevant docs" state this is based over, the threshold for this getting approved is basically just "fit the style/intent of the docs, and don't mislead users", so I'm not planning to ask for exhaustive coverage of everything involved (though by the looks of things you've already largely achieved full coverage anyway!) :-)
|
|
||
| The Cockpit-focused endpoint should including a name, version, iframe URL, and an optional URL for | ||
| configuration of each widget: | ||
| #### Configuring cockpit_extras.json |
There was a problem hiding this comment.
This heading is several levels too high to be in this location, but I actually think the problem is the location. There are several examples here that go beyond what normal users would need to know or care about, so I suggest moving this whole section to its own file (e.g. /content/development/external-integrations/index.md, with the images in the same folder), which can then link back to relevant points in this file from each subsection.
This location can then be used to link out to that file, for developers who want to explore the detailed breakdown/examples, without it affecting the standard users.
| You can make your BlueOS Extension interact with different elements within the Blue Robotics software suite by configuring | ||
| the `cockpit_extras.json` file. Keys are typed in `lowerCamelCase`. We recommend to type id values in `kebab-case`. |
There was a problem hiding this comment.
HTTP servers do not need to be from BlueOS Extensions - they could also be served by the computer running Cockpit, for example, or accessed via the internet (for operating conditions where that is viable).
If this gets introduced specifically as an example of making a BlueOS Extension integrate with Cockpit then that's potentially ok, but if it's intended just as a description of the functionality then it will need to be more general about the possible options.
| ``` | ||
|
|
||
| ##### Minimal configuration | ||
| A minimal `cockpit_extras.json` file can be seen below. This file does not add any extra functionality yet. |
There was a problem hiding this comment.
It seems worthwhile describing the key functionalities (e.g. custom iframe widget integrations, custom Actions, and custom joystick button mapping suggestions) before providing an example like this, but that can potentially be at the top of the page.
| ##### Widget configuration | ||
| You can add widgets to Cockpit based on your BlueOS Extension by adding a widget configuration. | ||
|
|
||
| | Attribute | Type | Required | Note | |
There was a problem hiding this comment.
If the table has no notes, it shouldn't include a column for them.
| | `iconUrl` | `string` | no[^1] | | | ||
| | `iframeIcon` | `string` | no[^1] | | |
There was a problem hiding this comment.
| | `iconUrl` | `string` | no[^1] | | | |
| | `iframeIcon` | `string` | no[^1] | | | |
| | `iconUrl` | `string` | one of | | | |
| | `iframeIcon` | `string` | one of | | |
Undecided if this is cleaner than the footnote approach. If you'd prefer to maintain the footnote then the word should still be changed (e.g. to "maybe" or "partial" or similar).
| Each joystick profile tracks its own set of applied and ignored suggestions independently. | ||
|
|
||
| ###### Joystick Mapping Suggestion Group | ||
| [Joystick Mapping Suggestions](#joystick-mapping-suggestion) must be contained in a Joystick Mapping Suggestion Group. This allows you to suggest multiple mappings based on what hardware is mounted for example. |
There was a problem hiding this comment.
| [Joystick Mapping Suggestions](#joystick-mapping-suggestion) must be contained in a Joystick Mapping Suggestion Group. This allows you to suggest multiple mappings based on what hardware is mounted for example. | |
| [Joystick Mapping Suggestions](#joystick-mapping-suggestion) must be contained in a Joystick Mapping Suggestion Group. This allows you to suggest multiple mappings based on what hardware is connected, for example. |
3 participants
🔎 PREVIEW 🔍
Documents: