tasmota
Documentation "Search" for script section (ie. >D) does NOT show existing content
Example:
Searching for script section gives "no matching documents" despite the search string being shown in Table of Content on the right. Maybe a configuration issue related to special characters like ">" is causing this issue?
PR https://github.com/tasmota/docs/pull/1460 uncovered an issue with theme mkdocs/material search being unsupported since 2020. Details are published in developer's blog post severe issues in theme "material"
Today I had a reboot loop with the text: "FRC: Some settings have been reset (3)". I seemed to remember having read about this somewhere, but did not manage to find it.
There is nothing worse than existing documentation that can't be found!
Never had such a bad search experience with documentation using theme "Read the Docs"
My journey:
- searching for exact wording =>0 hits
- Relaxing the wording =>0 hits
- allowing all words => just has way too many hits for being useful!
Usually it works well if you have a good single search word like FRC, but no hits.
Combined words can be searched like +boot +loop or "boot" "loop"
(Boot loops are what causes Tasmota to reset features until able without crashing again)
Usually it works well if you have a good single search word like
FRC
Unfortunately nearly all "sections" in Tasmota scripting language are only 2 char long (i.e. ">B") but material-theme search requires 3 chars as minimum for search to work!
@blakadder it seems you are the maintainer focusing on documentation, may I kindly ask for your view regarding future doc framework?
Usually it works well if you have a good single search word like
FRCUnfortunately nearly all "sections" in Tasmota scripting language are only 2 char long (i.e. ">B") but material-theme search requires 3 chars as minimum for search to work!
@blakadder it seems you are the maintainer focusing on documentation, may I kindly ask for your view regarding future doc framework?
If you are you asking me if I intend to change the entire documentation framework to fit the needs of a single documentation page while Ctrl+F exists?
No.
To be clear, I was only responding to your troubles with searching for a sentence, not about the reasonably useless searching for >D when there is only one page to look into for such.
change the entire documentation framework to fit the needs of a single documentation page
that was from my view just the last "nail in the coffin" of theme "material". It seems PR https://github.com/tasmota/docs/pull/1460 uncovering an issue with theme mkdocs/material search being unsupported since 2020. did go unnoticed. Details are published in developer's blog post severe issues in theme "material"
the reasonably useless searching for
>Dwhen there is only one page to look into for such.
Could you perhaps put yourself "into the shoes of a newbie" trying to understand a Tasmota script found in a forum. Now considering that perspective, would you mind to elaborate on that?
The point is that users searching for >D would not be "raw newbies", but come from a basis of wanting to use the scripter feature.
Sure, the rudimentary docs search box is far from being a "real search engine", for such you still have https://www.google.com/search?q=tasmota+">d" to zone in on relevant pages. And ctrl-F inside pages, of course.
More generally, while there is a Tasmota docs page about the scripter, it is not really great for wanting to understand a random script without already having spent a learning curve to get into the concepts of how the thing works. Meaning already knowing where the relevant docs page is.