Displaying supported sensors in README.md #439
Replies: 4 comments 18 replies
-
|
Yes, I totally understand the struggle you have with the table, I have the exact same thing and the same thoughts have crossed my mind how to make it better. the table, of course, has a history, it started small with a few sensors, which was readable. But now it has grown till what it is now. one possibility is grouping per advertisement format, so make a different table for qingping, xiaomi MiBeacon, govee, etc. another possibility that crossed my mind is splitting up the entire readme, with an individual page for
the introduction could have a short list with only the supported sensor types with a link to the second page. each page should have a link to the other pages. An additional idea is to create a different landing page for hacs, that refers to the pages on github. My experience is that the links in Hacs never work, as the are relative links. This would also have the advantage of not having to update the same things twice. For hacs we use the info.md page, which is basically a copy of the README.md with slightly changed links for pictures, to make them work. Personally, I have the best feeling with the second option, multiple pages |
Beta Was this translation helpful? Give feedback.
-
|
@Ernst79 I have to agree. The second option also crossed my mind; a few months ago I updated the Jekyll documentation for Heads ROM wiki (site, repo) and thought searching/tagging would help break down the information for each sensor. This also did not seem practical as it would not help the situation for If it isn't too assuming of me, I will experiment with rearranging the documentation for a github pages site. |
Beta Was this translation helpful? Give feedback.
-
|
Sure, that would be more than welcome. You still combine it with the first option, on the sensor page, you can still split up in sensors per advertisement format or something like that. Just to let you know, I’m currently working on writing unittests. I might ask you to send me some advertisements for govee sensors, to write the tests, but I will first create the basic setup. |
Beta Was this translation helpful? Give feedback.
-
|
Just looked at the link you had in your post, something like that also looks nice. I’ll let you experiment |
Beta Was this translation helpful? Give feedback.
-
|
@Ernst79 There is still quite a bit of polishing still to do but wanted to make sure this would work for the project. https://home-is-where-you-hang-your-hack.github.io/ble_monitor/ A few notes:
The main difference is now devices have been split up into individual markdown documents with parameters in YAML headers that are used to populate templates based on criteria. Currently the only page that works like this is supported devices by manufacture where devices are grouped under manufacture. I want to add a page where users can search by the broadcasted property such as "temperature". The YAML headers can include any information and can query the information by whatever seems appropriate (all devices with encryption, all devices that require active scan, etc). When a new device is added, just the device markdown file will need to be with the required header information (I'll add a template), and all of the various device queries will be populated. |
Beta Was this translation helpful? Give feedback.
-
|
Whoaw, this looks very good! I’m very impressed, looks so much better than the old (extremely long) page. Don’t forget to put yourself at the credits 😄 |
Beta Was this translation helpful? Give feedback.
-
|
@Thrilleratplay I'm not sure if it is possible, but as you might have seen, I have created a pypi package ( |
Beta Was this translation helpful? Give feedback.
-
|
@Ernst79 Of course. I'll finish cleaning up what I currently have and update it for the newest devices. If I do not have too many distractions, I should have that done or presentable by the end of the day. When reading #34, I assumed the standalone parser was going to be lower level, like aioblescan or bleson, but this makes more sense. The way the documentation is being generated, each device can have whatever relevant data added it it but displayed in a way that is fitting (HomeAssistant user level vs dev user level). Before creating dev level documentation, some ambiguities that exist should be clarified or at least rewritten (examples: "probably encrypted (not confirmed yet)", "we do not have accurate periodicity information yet" and many of the broadcast rates). Again, let me finish my current restructuring of the current documentation and then it should be easier to see what is needed for developer level documentation. |
Beta Was this translation helpful? Give feedback.
-
|
For About the documentation, let me know when I need to help getting this developer level info updated. There is no hurry. It's holiday season here, so I will spend a little less time after this week for a couple of weeks. |
Beta Was this translation helpful? Give feedback.
-
|
@Ernst79 I enabled github pages mainly to ensure that the Jekyll config settings worked correctly for this repo. https://custom-components.github.io/ble_monitor/ I had difficulty getting the relative path of the image assets correct. As I was typing this, I also remembered using I am not sure how much information to be left in README.md and info.md, I'll leave that up to you. I will also add a page for ble_parser to begin incorporating that information. @Magalex2x14 If you have the time, can you also review https://custom-components.github.io/ble_monitor/ to ensure there is no misinformation or missing information? |
Beta Was this translation helpful? Give feedback.
-
|
Thanks, fixed. Will look into the readme and info.md tomorrow. I think I make it very small, only a short description and a link to the docs, faq, etc. |
Beta Was this translation helpful? Give feedback.
-
|
I try to tweak the layout a bit more, as I would prefer to have a title on top of the page. I managed to get the TOC below the Title and a short text, but the original TOC is also still above the Main title. Is it possible to remove the top TOC?
|
Beta Was this translation helpful? Give feedback.
-
|
Nevermind, figured it out, its in default.html |
Beta Was this translation helpful? Give feedback.
-
|
Made some tweaks in the layout and corrected some heading levels. Also fixed the README.md and info.md. That's it for today :smile |
Beta Was this translation helpful? Give feedback.
-
|
I ran into that too, where I would want to display one header which did not need a TOC. Use the <span class="fake-h1">Encrypted Advertisements</span> |
Beta Was this translation helpful? Give feedback.
-
When adding the Govee devices to README.md, I found adding the line " Govee devices only send data with the option active_scan set to True, so make sure you change this setting, as the default is False" to every device was redundant. What started off as a change to add a column to the Supported Sensors table turned into an attempt to "simplify" the table.
This did not turn out as well as I hoped. An attempt to group like devices by shared functionality became confusing as there are enough differences (example: does an alarm clock that transmits temperature and humidity go under Thermometers/Hydrometers?). Additionally many devices are manufactured under different brands with and without variations so grouping by brand cannot be done. Instead it was left as one table, but close to finishing but see a table that is more complicated than when I started.
Perhaps I am over thinking it and am solving a problem that does not exist. If it is an issue, the only thing I can think of is to leave a list of sensors in the README with a link to specific device details in another markdown file. This however may lead to information being missed.
Thoughts? Concerns? Ridicule?
Beta Was this translation helpful? Give feedback.
All reactions