mycroftai / documentation Goto Github PK

I've been looking around and haven't found a document that seems to detail what a dev should do to make thier skills compatible with MSM. Can we get a link to such a document attached to the text:

It is important that you make your Skills compliant with msm so that they are easy to find and install in the future.

It's full of outdated stuff. See #121 (comment) and the ensuing conversation.

A few months ago, I tried to run Picroft in a machine that I could control via a bluetooth headset.
After multiple frustrating attempts, I stumbled upon the reason why no configuration or OS permitted me to do that : the Raspi 3's bluetooth drivers do not support audio input.

Just thought a note of this could be made here : https://github.com/mycroftai/docs-rewrite/blob/master/_pages/picroft-audio.md to avoid haing other people try the same thing I did #

Mycroft has come a long way over the last few years and our documentation has not always kept up. Skill Development is certainly one of these areas. New methods and tooling are available for developers, but the documentation still encourages old (sometimes deprecated) practices.

We want to update this section of the documentation with a Skill Development series, that provides a really easy to follow tutorial for beginners, and progresses through the many components available in a logical and structured way.

This issue is an attempt to provide the bones of that structure. Dot points are listed as check boxes because each is a page of documentation that needs to be compiled from existing sources, or written from scratch.

Skill Development

Intro

• Introduction to Mycroft Skill Development
• Your first Skill - including using msk create and a brief run through of what this generates
• Logging
• Intents
  • Intro to intents - what are they, what are entities and overview of the built in intent parsers.
  • Padatious Intents
  • Adapt Intents
  • Mycroft Intent Service
• Skill lifecycle methods - init, initialize, stop, shutdown
• Skill settings - why, how, best practices
• Dependencies
• MycroftSkill methods available - directing to the technical docs

Managing interactions, follow-ups and conversations

• Asking question - intro to get_response() and similar methods
• Conversational context
• Converse()
• Communicating with a RASA instance

Automated Testing

• Replaced with Voight Kampff docs

Different Skill Types

• Fallback Skill
• Common Play Skill
• Common Query Skills
• Common IoT Skill

GUI and Display Control

• Mycroft GUI with Qt - 1, 2
• Controlling the Mark 1 display

Voice User Experience - Designing your Skill

• VUX Design Guidelines

Language and internationalisation

• Skill translation process
• Best practices for enabling broad adoption of your Skill

Skill Submission

• Skills Acceptance Process
• Required components for your Skill
• README.md tips
• Upgrading a Skill

Other (where should these go?)

• Specific how-to's eg setting up Home Assistant, or getting HA notifications via Mycroft

If any of these topics interest you, please consider learning about the topic and solidifying that learning by updating the documentation for it 😀

The pages that describe signing up for a Mycroft account need to document clearly:

(1) why Mycroft needs to have an account on some server outside the home,
(2) exactly what data is transmitted from my home Mycroft appliance(s) to servers outside the home,
(3) exactly what data is retained on servers.

People are looking to Mycroft and other open source packages precisely because they worry about the access to private/personal information which mega-corporations are gaining with mainstream devices.

The Documentation section of the Mycroft.ai website uses a separate Page Template, which includes the 'Reading Time' and 'Multiratings Pro' plugins to provide additional functionality that is used only for the Documentation section.

The blue navigation section, which includes Breadcrumbs and Search, does not wrap properly on smaller screen resolutions. Some CSS work is required to redesign the HTML/CSS so that it wraps more responsively.

See attached screenshot for example.

Provide documentation on naming packages and skills with the word 'Mycroft'

From @zackwelch in Mycroft Chat:

An official prohibition of plug-in or add-on packages from using "mycroft" in their names seems counterproductive when one extends that policy to, e.g., package management or product brand development.
i am curious what the official policy is in these regards... i don't remember seeing a page describing trademark usage and similar issues
if one actually exists, it certainly would be beneficial to have a package naming policy documented as part of the developer tutorial (wherein the user is guided to copy the template to a new project directory)

Breaking this down into specific actions, I think this is what needs to happen:

• Define a Skill naming standard that reserves the 'Mycroft' keyword for Mycroft-supported Skills
• Define documentation that explains how the Mycroft trademark is used, and how it can be used by developers. This would need to align with the use of the Apache 2 license on our open source code.

Received via feedback on the page;

Hello,

A new rating #119 by "Anonymous" has been approved.

Date: July 11, 2018, 6:39pm

Comment: I am using Firefox and the table on this page does not fix the screen and I don\'t get a scroll bar to see the parts off the screen. Must be part of some css.
Overall Rating: 60%	
Documentation ratings: Average - sections are outdated or need clarification 

Thank you.

This issue was validated, screenshot below;

Had a quick look - the MarkDown to HTML formatting simply uses the <table> and related tags - here are no class or id attributes added which would be useful for CSS styling. Possible approach here is to use more specific selectors to word-wrap within <td> elements. Posting as an Issue because I don't have time to fix right now.

https://github.com/MycroftAI/docs-rewrite/blob/master/LICENSE.md

This link does not exist and it is referenced in the README file located here:

https://github.com/MycroftAI/docs-rewrite

If a mic is registering but seemingly unable to pick up voice commands, it can be that the mic level is set very high. Try reducing this to 50% or lower and see if behaviour changes.
Example issue: https://community.mycroft.ai/t/no-voice-recognition/6477

I found this link:
https://mycroft.ai/documentation/skills/automatic-testing/#how-to-define-tests-for-your-skill

And asked myself, how can I do this in a different language?

Or in a multilingual way?

Defining the utterance as de-de or en-us?

Is it done via the context, or some other way?

The documentation should give an example here, if implemented.
Otherwise it is an issue for the skills section. As testing utterance only in one language is way to less.

Section Add a Git submodule for your Skill of "Preparing your Skill for submission to the Mycroft Skills Repo" speaks of having cloned the mycroft-skills repo in the past tense. I recommend a small paragraph that spells that out in a little more detail. Maybe under its own heading immediately before this section.

Also, this would be an opportunity to describe the preferred repo and branch usage and naming. I.e.,:

• Should we clone https://github.com/MycroftAI/mycroft-skills directly to local working copy? Or should we first make our own fork of the repo?
• should we work on private master branch? Or should we create a branch and make changes to the branch? If so, what is the preferred naming scheme? e.g., add-skill-name or feature/skill-name or public-skill-username-skill-name, etc
  Further down the page, in bullet point three of Submit a PR (Pull Request) in GitHub to have your Skill listed , the implicit assumption appears to be no new branch, and the submitter would issue PR from their private fork's master branch: "This will usually be MycroftAI/mycroft-skills/master and YourGitHubUsername/mycroft-skills/master"

the language support docs make a few wrong assumptions:

• wakeword must be in new language
• pocketsphinx models must be downloaded
• pocketsphinx offline STT prs must be merged

Wakeword:

• wakeword supports a language parameter, so we can use english wake words

• i actually recommend this because phonemes are different in other languages, so expect a bunch of questions why phonemes don't work

• docs should say downloading pocketsphinx models is optional, and warn about different phonemes

Language:

this part is just wrong, in the sense that those are instructions for a unmerged PR, that is not related to this task at all, new STT != adding new language

As an alternative, you can use PocketSphinx, running on your local machine. To use PocketSphinx as your STT engine, add the following to your mycroft.conf file:

    "listener": {
       "producer": "pocketsphinx",
       "grammar": "lm"
       }

• it depends on 1 of 3 possible PRs for pocketsphinx, the oldest and closed one!
• Pocketsphinx accuracy is not good, users will not only be confused but also have bad performance if they somehow succeed
• it's unclear that the default stt (mycroft/google) supports most languages and is the most accurate one, mycroft supports most languages by default, why make it seem so arcane and difficult?
• "If the Speech to Text engine you are using already supports Spanish, you don't need to do anything." is super vague, why not have a list of supported languages instead?
• TTS support just recommends using espeak, i spent quite some time investigating available TTS and supported languages

There's lots of optional steps being given as mandatory, and some important things just missing, there is no mention of translating individual skills for example, and the remote config will likely cause trouble for those following the guide, i don't think you want to tell people to disable home.mycroft.ai for this purpose, so the guide should include pictures of using the home portal and not only the config :)

here is my guide for language support https://jarbasai.github.io//posts/2017/09/language/

The link labled "Simplifying your Skill code with intent_handler decorators" at the top of the Developing a new skill page
contains a URL anchor that is incorrect. Destination href:
https://mycroft.ai/documentation/skills/introduction-developing-skills/#simplifying-your-skill-code-with-intent_handler-_decorators_

is invalid. probably those underscores are formatting that leaked into href. There does exist this anchor:
"#simplifying-your-skill-code-with-intent_handler-decorators" which is surely what should have been in the href attribute.

Dependencies section needs to include info on manually installing python packages to the Mycroft virtual environment using mycroft-pip install

From https://mycroft-ai.gitbook.io/docs/skill-development/your-first-skill

If you chose the defaults during installation, you can run MSK from your Terminal using the command: mycroft-msk [...] If you receive a "command not found", then you will need to run msk manually from your mycroft-core directory. Anytime you see mycroft-msk in our documentation you must replace this with:

0. The Documentation (https://mycroft-ai.gitbook.io/docs/) should really link to its issue tracker, I posted this on the Forum first, thinking there was no better way.

1. The last sentence is incomplete: the next word is in the next heading

2. I did use the defaults (or actually I always entered y I don't remember any indication of which of them was the default) during installation of the current version (commit c2904335f6f4 from 2019-11-14 on master). My only deviation is that I installed it in /opt instead of /home. There is no mycroft-msk for me, but there is no msk either!
   Instead I have to go to (/opt/)mycroft-core/bin and then
   ./mycroft-msk

Update:

I've picked up that one must install msk with source venv-activate.sh; pip install msk.
This should really be in the documentation!

It should be /dev/ttyAMA1 not /dev/ttyAMA0

From feedback from @normandmickey via Mycroft Chat

You should mention that the first step is to fork the Mycroft-skills repo and then clone your fork to your computer. The way the instruction read now they just say to clone the Myskills-repo.

Observing a minor css problem on https://mycroft.ai/documentation/skills/skill-settings/ . The navigation breadcrumb trail in the header has text color the same as the background when in a non-hovering state. This makes the element "invisible" until you hover over it. This was using Chrome. Also note: I visited a couple of other pages in Mycroft Documentation that did not exhibit the issue, so it is probably not a master/global CSS issue.

"relevant" would be a better word than "relative" in this paragraph: Generate a README.md file for your Skill

In the paragraph following, "the" instead of "this" preceding plural "sections"

Partial extension of #3 : My first read of Add a Git submodule for your Skill made me think I was supposed to execute the command "mycroft-skills" which is a valid executable name! I therefore recommend two things:

1. make sure the "mycroft-skills" (in monotype) is inline, not on next line,
2. give it preceding and following queue words and punctuation.

So something like:
Next we need to add the Submodule for your Skill to the mycroft-skills repository. For more help on Submodules in GitHub, feel free to check out this guide

Or, type the following git command in the terminal, assuming you are in the directory where you cloned the mycroft-skills repository:

git submodule add $remote $name-your-skill

where $remote is the git address for your repo [example]

For an unknown reason, I had an issue with the order of the adds_context and removes_context when working with the "Using context to enable Intents" part of the "conversational-context.md" guide (HERE).

When I answer 'yes' to 'would you like milk with that', I get 'what about honey' to which I respond 'yes' and then the 'you might have to say that a different way'. The same occurs vice versa when I answer 'no' instead of the 'yes'. It only works when I reverse the order of the adds_context and removes_context in the NoMilkIntent and YesMilkIntent -- i.e., when the adds_context comes before the removes_context. I don't know why it should make a difference, and I recall it working in either order sometime ago (but I might be wrong). There are no error messages in the mycroft-cli-client. And I'm using Picroft (Mycroft-Core ver. 18.2.4 beta).

Note that I also needed to make a few fixes for the TeaSkill example to work. See my pull-request (#57) for recommended changes to the "Using context to enable Intents" part of the "conversational-context.md". I did not include this issue in my pull-request (#57) as they seem to be two different problems.

It would be nice to have the documentation available as a pdf file. This would make it possible for off line viewing and allow people to put it on e-readers such as kindles.

https://mycroft.ai/documentation/skills/#community-developed-skills

Resulting in a bunch of 404s.

Fix: update doco to link to the Skill's GitHub repo instead

Description of Issue in object-deviation format

The docs-rewrite repo content is authored in the MarkDown markup language, and is then consumed by WordPress, where a plugin renders the MarkDown into HTML, which is styled using the WordPress Salient Theme styling.

Unfortunately, some elements like <pre> and <code> are difficult to read as shown in the screenshots below.

Current CSS rules used to style these elements

pre, code {
    font-family: 'Ubuntu Mono', monospace;
    display: inline;
}

Suggested solution

Improve the CSS styling for these elements so that they are more readable

Screenshots of the problem

User story

As an advanced Mycroft user, I want to have the ability to disable a Skill without deleting it from /opt/mycroft/skills

Acceptance criteria

• New documentation on how to disable a Skill in mycroft.conf, ie:

{
  "skills": {
    "blacklisted_skills": ["skill-media", "send_sms", "skill-wolfram-alpha, YOUR_SKILL"]
  }
}

• New documentation is linked to from the menu structure

The description of the dialog directory and its contents does a good job of introducing basic mechanism and parts and illustrating usage, but it makes no mention of the double-curly-brace substitution tokens feature which is used by the speak_dialog method .

On this page:

https://mycroft.ai/documentation/adapt/

in the section:

Installing Adapt for Ubuntu, Debian or Raspbian

in the code block to install Adapt via pip inside a virtualenv, the commands mentioned in the code block are mentioned twice. Screenshot:

"vocab directory and defining Intents" section needs more detail. Particularly: the current example shows the simplest case of single-vocab-element/phrase. Notably missing is a little explanation about the intent handlers' chaining of the "require" method and how that relates to the vocab files. And also importantly: assuming this permits some word or words not specified by a vocab file to appear in between vocab elements, what words are allowed there? what words reliably can appear there? Only articles? Any word, as long as less than 3 of them? or any word as long as they don't collide with other intents?

Mycroft has an internal event scheduler mechanism, referred to in this forum discussion: https://community.mycroft.ai/t/running-background-processes-with-skills/2986/4?u=jrwarwick

Would benefit greatly from general introduction, "does-and-don'ts" for usage, some simple examples. For now, it looks like the auto-generated API doc has some useful info:
http://mycroft-core.readthedocs.io/en/stable/source/mycroft.html#mycroft.MycroftSkill.schedule_event
but the methods are spread out and descriptions are not detailed.
Also: allowable (and preferred) methods of persistent data and state between executions.

Great suggestion by @zachwelch
@kathy-mycroft: incidentally, the CLA seems like the kind of thing that should be mentioned prominently on this page https://mycroft.ai/documentation/contributing/

Skill publishing documentation found at: https://mycroft.ai/documentation/skills/skill-submission/#submit-a-pr-pull-request-in-github-to-have-your-skill-listed

Is describing how to ultimately make edits to the Mycroft project public skills repository. It looks like there is an error here. Instructions say ", go to the GitHub repo for your Skill. Click the 'New Pull Request' button as shown in the image below" . But in this case, don't we actually want to create a pull request between our fork of the mycroft-skills repository (instead of our skill)? Isn't that where we would be making publishing details changes?

Note that the screenshot of a sample skill repo also (consistent with the instructions) is not correct.

We have a list of basic commands available in the default Mycroft Skills:
https://mycroft-ai.gitbook.io/docs/using-mycroft-ai/basic-commands

This is a very short list with only one or two utterances per Skill. To help new users understand the range of functionality available, it would be great to extend this list to cover all major functions of each Skill.

To add to this list, just use a Mycroft Skill and document the utterances that are most useful to you. You can do this by cloning the repository, or editing the list directly in the browser:
https://github.com/MycroftAI/documentation/blob/master/docs/using-mycroft-ai/basic-commands.md

Technical documentation on the different parts of the integration test runner to test Mycroft skills by emulating the users spoken utterances.

I've seen some skills such as ping-skill that have an optional regex subdirectory with tokenized regular expression specification files. I've seen elsewhere a mention of Adapt intent parser's support for this, but it is sparse and not clear. This could use quite a bit of explanation.

Under How do I use skill settings we see an example of calling self.settings.get() method with a single argument. However, later, pianobar-skill is cited as an exemplar, and it makes a method call with a second argument of an empty string, with no apparent explanation. Moreover, the autogenerated API seems to lack docstrings that would explain the optional arguments. Therefore, I am recommending not only an enhancement here in docs-rewrite, but also that it would spawn an edit/update to the core source such that API auto-gen docs would yield an overview on settings.get() method and its calling arguments.

Description in object-deviation format

Using Safari browser on iPad, the Skills page does not render and instead gives a warning to load Javascript. This was validated using both BrowserStack and by user kurt_r in Mycroft Chat (thanks, Kurt!).

Workaround

The only available workaround is to use an alternative browser such as Chrome. Chrome has been confirmed to work.

Was flagged using Documentation feedback mechanism on page

Site Admin via sendgrid.net 
Sat, Sep 1, 7:02 AM (3 days ago)
to me

Hello,

A new rating #136 by "Anonymous" has been approved.

Date: August 31, 2018, 4:02pm

Comment: Not loading on safari, iPad.
Overall Rating: 20%	
Documentation ratings: Poor - inaccurate or misleading or very outdated 

Thank you.

From the Skill Submission page the link to generate a readme.md should be:
https://raw.githack.com/MycroftAI/mycroft-skills/18.08/meta_editor.html

The section Add a Git submodule for your Skill should be updated as it does not completely agree with or reflect confirmed naming standard for skills.
Authoritative references:
https://github.com/MycroftAI/mycroft-skills#4-add-your-skill-as-a-submodule
https://community.mycroft.ai/t/skill-naming-format/2349/5

Bring info from Wiki into primary docs.
https://github.com/MycroftAI/mycroft-precise/wiki/Training-your-own-wake-word#how-to-train-your-own-wake-word

Some learnings from users include:

• MycroftAI/mycroft-precise#94

On https://mycroft.ai/documentation/picroft/#downloading-the-disk-image, the sentence:

If you’re concerned about privacy with Picroft’s WiFi setup, you can inspect our Wifi Client code on GitHub.
has a broken link: https://github.com/MycroftAI/mycroft-core/tree/dev/mycroft/client/wifisetup

I poked around a bit but haven't found the new, correct link.

Submit a PR (Pull Request) in GitHub to have your Skill listed has a few opportunities for improvement:

• third bullet:
  "You will need to choose with repositories to compare and create a PR from"
  probably should be:
  "You will need to choose which repositories to compare and create a PR from"
• Fourth bullet includes some code-sample/mono-space text. I think it would look better if indented to
  appear to be "child" content of the bullet
• And then, consider making this last line a fifth bullet:
  "Fill in the PR template and submit your PR."

Also, if outstanding issue MycroftAI/mycroft-skills#274 is confirmed and addressed, the template example text in fourth bullet should be updated.

I keep getting distracted, so I'm throwing this here. Either I won't forget, or somebody else will beat me to it.

In at least a couple of places, including the "Introduction to Writing Skills" tutorial, people are offered from mycroft.skills.core import MycroftSkill. I've discovered (thanks Kite!) that it's deprecated in favor of from mycroft import MycroftSkill. Those references should be changed.

While trying to make USB Logitech Headset H340 work for picroft, I found some bits of the documentation to be either obsolete or not clear enough. The one I can remember now is:

• https://mycroft.ai/documentation/picroft/#audio-issues
  "By default, Picroft uses the PulseAudio subsystem (...) pacmd list-sources"
  Either picroft does not use pulseaudio, or pacmd was not installed in the image I was using.

Also (offtopic probably) I'd like to know if it'd be possible to make the Logitech Headset H340 a supported device. I think I just changed alsa.conf to have it working, but I'll test deeper soon

On this page the link to the python tutorials yields a 404.

https://mycroft-ai.gitbook.io/docs/skill-development/introduction

In the documentation for "Developing a new Skill"
(link https://mycroft.ai/documentation/skills/introduction-developing-skills/)

it is stated

'
Then,
git clone
the repo you've just forked to your local machine.

For example, if your GitHub username is "JaneBloggs" then you will need to
git clone
from https://github.com/JaneBloggs/mycroft-skills.git
$ git clone https://github.com/JaneBloggs/mycroft-skills.git
'

However, I cannot clone the entire skills repository like this, I only end up with empty directories locally. The only way I can clone the skills is to clone the skills individually.

The section heading "init.py" (anchored at https://mycroft.ai/documentation/skills/introduction-developing-skills/#__init__-py ) is styled like a code block content instead of a section header. I think this makes it less clear that a new section has begun.

In section [Make a new repo using the Template Skill] (https://mycroft.ai/documentation/skills/introduction-developing-skills/#make-a-new-repo-using-the-template-skill ) there is an incorrect commandline:

$ cp -R 00__skill_template skill-hello-worldls -las

That should be broken into two commands:
$ cp -R 00__skill_template skill-hello-world
$ ls -las

or else perhaps
$ cp -R 00__skill_template skill-hello-world ; ls -las

This was discovered by new developer ragesoss (from Mattermost)

On page: https://mycroft.ai/documentation/skills/introduction-developing-skills/#prerequisites
there is a hyperlink labeled: "Mycroft for Linux" that points to URL: https://mycroft.ai/documentation/skills/introduction-developing-skills/Mycroft-for-Linux.md which appears to not exist, so following the link gives a 404 error.

Received via feedback on mycroft-software-hardware page

Date: January 24, 2019, 12:51am
it looks like you forgot to mention that Google STT records everything someone says to Mycroft and sends it to Google (per Jasper (another open-source assistant) developers http://jasperproject.github.io/documentation/configuration/).

Add description of how Mycroft uses Google STT and anonymizes data sent to that service as much as possible.