mycroftai / documentation Goto Github PK
View Code? Open in Web Editor NEWMycroft.AI documentation for all public facing technical components.
Home Page: https://mycroft.ai/documentation
License: Apache License 2.0
Mycroft.AI documentation for all public facing technical components.
Home Page: https://mycroft.ai/documentation
License: Apache License 2.0
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.
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.
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.
pre, code {
font-family: 'Ubuntu Mono', monospace;
display: inline;
}
Improve the CSS styling for these elements so that they are more readable
On this page the link to the python tutorials yields a 404.
https://mycroft-ai.gitbook.io/docs/skill-development/introduction
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
It's full of outdated stuff. See #121 (comment) and the ensuing conversation.
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.
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/
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 runmsk
manually from yourmycroft-core
directory. Anytime you seemycroft-msk
in our documentation you must replace this with:
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.
The last sentence is incomplete: the next word is in the next heading
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!
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.
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.
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
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.
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:
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
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 .
As an advanced Mycroft user, I want to have the ability to disable a Skill without deleting it from /opt/mycroft/skills
mycroft.conf
, ie:{
"skills": {
"blacklisted_skills": ["skill-media", "send_sms", "skill-wolfram-alpha, YOUR_SKILL"]
}
}
"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"
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)
Technical documentation on the different parts of the integration test runner to test Mycroft skills by emulating the users spoken utterances.
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.
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.
msk create
and a brief run through of what this generatesget_response()
and similar methodsIf any of these topics interest you, please consider learning about the topic and solidifying that learning by updating the documentation for it 😀
the language support docs make a few wrong assumptions:
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"
}
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/
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!).
The only available workaround is to use an alternative browser such as Chrome. Chrome has been confirmed to work.
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.
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:
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
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.,:
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:
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.
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.
Dependencies section needs to include info on manually installing python packages to the Mycroft virtual environment using mycroft-pip install
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.
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:
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.
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
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.
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.
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.
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:
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]
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 #
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
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:
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.
Submit a PR (Pull Request) in GitHub to have your Skill listed has a few opportunities for improvement:
Also, if outstanding issue MycroftAI/mycroft-skills#274 is confirmed and addressed, the template example text in fourth bullet should be updated.
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.
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.
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 should be /dev/ttyAMA1
not /dev/ttyAMA0
"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?
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.