Fundamental description of Adapt Intent Parsing

[david-morris]

Is your feature request related to a problem? Please describe.
I spent a lot of time debugging Adapt intents because I did not know the basics of how Adapt intents work. I ended up reading intent.py in Adapt, but I don't think that's an ideal solution.

Describe the solution you'd like
I think the Adapt Intents documentation would be more useful with some basic rules about how keywords and regexes combine to form intents, such as:

• Keywords consume text
• Regexes do not consume text
• optionally and one-of terms are in separate lists in Intent objects, activating in the intent strictly after all required terms.
• There is no way to determine whether a term consumes or does not consume text.
• There is no way to determine whether a term runs on the utterance or utterance remainder.
• (It seems) regexes must match the entire utterance remainder.

Also, general pointers would be good. I'm going to try overhauling the skill I'm working on, so that it focuses on keywords and utterance remainders more. Is that what I should have been doing from the start? Maybe there should be a suggestion in the Adapt Intents documentation.

Describe alternatives you've considered
Alternatively, intent.py could be linked from the Adapt Intents documentation. If I'd known beforehand that this is the file to understand how to build compound intents, it wouldn't have taken as long to figure it out. In the same vein, links to skills that show good use of adapt would also be useful.

Outside of documentation, having more flexibility in the matching of adapt intents could be useful, as could adding something like self.match_voc for regexes in the basic Skill class. Matching regexes on the utterance rather than the utterance remainder cannot be made default now, but might have better adhered to the rule of least surprise, and would simplify future regex building. Perhaps a switch could be added for this behavior?

Additional context
I have been contributing to pcwii's cpkodi-skill.

[oblitum]

I think something in this sense is sorely necessary.

[krisgesling]

Very much agree, these need a lot more detail.

This also fits nicely with the push toward Adapt v1.0 👍