Switch to HTML for generated device documentation #51
Closed
opened 2 years ago by izzy
·
3 comments
No Milestone
1 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: izzy/Adebar#51
Loading…
Reference in new issue
There is no content yet.
Delete Branch '%!s(<nil>)'
Deleting a branch is permanent. It CANNOT be undone. Continue?
Currently, device documentation is generated as Markdown – no specific flavor, to be widely compatible. That restricts formatting quite a bit, which is why Adebar almost completely uses only headers and lists. As a result, there's a lot of scrolling, and information often isn't easy to grasp.
A good idea would be switching to HTML+CSS (no JS, though), which would give a lot of flexibility: tables, coloring/theming, even some responsiveness – plus it can easily be viewed in any web browser, without the need of some "conversion tools".
I took an existing device documentation, stripped the app listings down a bit, and created a mockup (CSS) which even has some responsive parts. Not being a big designer, I'd welcome feedback on this before I start rewriting. I've used classes and ids quite a lot to hopefully make styling easy; if you think there's some id/class missing somewhere, please say so (e.g. each section/table could get its own id, so CSS could even reorder items). Alternative style sheets are welcome, too – after all, they come as separate files, so no need to restict us to a single one; Adebar could even by default ship several.
Looking forward to your feedback and ideas!
If you use Adebar, feedback is welcome: first implementation was checked in to the devel branch. Please test if it's working for you and let me know what needs fixing/improving. Already on my list: adding IDs to the tables so you can address them directly via custom CSS.
47a4f4eadded IDs to tables. Now I'm looking forward to your feedback – and maybe suggestions to improve the CSS.Completed at
802a80cab6. Still open for CSS improvements.