From 0f1e5573a8ec31e94c343ec6585cc659708594dd Mon Sep 17 00:00:00 2001 From: Daniel McKnight <34697904+NeonDaniel@users.noreply.github.com> Date: Thu, 16 May 2024 16:40:49 -0700 Subject: [PATCH] Move definitions in FAQ to Definitions (#57) Add link in Configuration to `skill_id` doc Add link in "Installing Skills" to `skill_id` doc Closes #24 Co-authored-by: Daniel McKnight --- docs/overview/definitions.md | 25 +++++++++++++++++++- docs/overview/faq.md | 28 ++--------------------- docs/quick_reference/configuration.md | 2 ++ docs/quick_reference/installing_skills.md | 3 +++ 4 files changed, 31 insertions(+), 27 deletions(-) diff --git a/docs/overview/definitions.md b/docs/overview/definitions.md index 3fb82812..1ee0589e 100644 --- a/docs/overview/definitions.md +++ b/docs/overview/definitions.md @@ -108,4 +108,27 @@ Structured plaintext files that define a skill's responses. ### regex (rx) Structured plaintext files that define -[regex parsing](https://docs.python.org/3/howto/regex.html) for a skill. \ No newline at end of file +[regex parsing](https://docs.python.org/3/howto/regex.html) for a skill. + +### Skill ID +A skill ID is used to identify a globally unique skill, and generally follows the +format of `.`. For most skills, this is specified +[in setup.py](https://github.com/NeonGeckoCom/skill-about/blob/d0796bbbdf37cb53dfe583e701048331f5e9731e/setup.py#L35). +For older skills without a `setup.py` the skill ID is specified as the directory +containing the skill's `__init__.py`; tools like `msm` and `osm` install skills +to directories matching the usual format, using information from a git URL or +[skill.json](https://github.com/NeonGeckoCom/skill-about/blob/dev/skill.json#L48-L49). + +### Package name +A skill package may be created with an arbitrary package name +[in setup.py](https://github.com/NeonGeckoCom/skill-about/blob/d0796bbbdf37cb53dfe583e701048331f5e9731e/setup.py#L87). +This identifier is used for installing the skill or listing it as a dependency like other +Python packages. If the skill is uploaded to PyPI, then it may be installed by package +name using pip (i.e. `pip install neon-skill-about`). Older skills that are not packaged +will not have a package name. + +### Skill Class +A [skill class](https://github.com/NeonGeckoCom/skill-about/blob/d0796bbbdf37cb53dfe583e701048331f5e9731e/__init__.py#L45) +generally has a descriptive name and is capitalized according to [Python standards](https://peps.python.org/pep-0008/#class-names). +This class is referenced in the [setup.py entrypoint](https://github.com/NeonGeckoCom/skill-about/blob/d0796bbbdf37cb53dfe583e701048331f5e9731e/setup.py#L35) +but is otherwise not referenced directly. diff --git a/docs/overview/faq.md b/docs/overview/faq.md index 644d1b0f..4594e906 100644 --- a/docs/overview/faq.md +++ b/docs/overview/faq.md @@ -54,29 +54,5 @@ green on boot or red on shutdown. The LED ring will light up white to confirm the reset and indicate you can release the buttons. ### What is a Skill ID vs a Package Name vs a Class Name -Skills can be identified differently in different contexts. The definitions here -will use the [About Skill](https://github.com/NeonGeckoCom/skill-about) as an -example. - -#### Skill ID -A skill ID is used to identify a globally unique skill, and generally follows the -format of `.`. For most skills, this is specified -[in setup.py](https://github.com/NeonGeckoCom/skill-about/blob/d0796bbbdf37cb53dfe583e701048331f5e9731e/setup.py#L35). -For older skills without a `setup.py` the skill ID is specified as the directory -containing the skill's `__init__.py`; tools like `msm` and `osm` install skills -to directories matching the usual format, using information from a git URL or -[skill.json](https://github.com/NeonGeckoCom/skill-about/blob/dev/skill.json#L48-L49). - -#### Package name -A skill package may be created with an arbitrary package name -[in setup.py](https://github.com/NeonGeckoCom/skill-about/blob/d0796bbbdf37cb53dfe583e701048331f5e9731e/setup.py#L87). -This identifier is used for installing the skill or listing it as a dependency like other -Python packages. If the skill is uploaded to PyPI, then it may be installed by package -name using pip (i.e. `pip install neon-skill-about`). Older skills that are not packaged -will not have a package name. - -#### Skill Class -A [skill class](https://github.com/NeonGeckoCom/skill-about/blob/d0796bbbdf37cb53dfe583e701048331f5e9731e/__init__.py#L45) -generally has a descriptive name and is capitalized according to [Python standards](https://peps.python.org/pep-0008/#class-names). -This class is referenced in the [setup.py entrypoint](https://github.com/NeonGeckoCom/skill-about/blob/d0796bbbdf37cb53dfe583e701048331f5e9731e/setup.py#L35) -but is otherwise not referenced directly. +Skills can be identified differently in different contexts. See +[definitions](./definitions.md#skill-id) diff --git a/docs/quick_reference/configuration.md b/docs/quick_reference/configuration.md index 635efac8..8c6c6151 100644 --- a/docs/quick_reference/configuration.md +++ b/docs/quick_reference/configuration.md @@ -86,6 +86,8 @@ skills: - ``` +> The `skill_id` here is usually something like `skill_name.author`. See also [definitions](../overview/definitions.md#skill-id) + > More information about skills can be found [in the OVOS docs](https://openvoiceos.github.io/community-docs/080-ht_skills/). ### Change the Wakeword diff --git a/docs/quick_reference/installing_skills.md b/docs/quick_reference/installing_skills.md index cfd77645..5b8550d6 100644 --- a/docs/quick_reference/installing_skills.md +++ b/docs/quick_reference/installing_skills.md @@ -4,6 +4,9 @@ to specify additional skills as [described below](#configuring-extra-skills), or you can manually install a skill like any other Python package (i.e. `pip install `). +> `` here is usually a [package name](../overview/definitions.md#package-name), + but may also be a git spec like `git+https://github.com/neongeckocom/skill-about@dev`. + > [OVOS Skills Manager](https://openvoiceos.github.io/community-docs/osm/) (OSM) > was previously recommended here but support has been deprecated. Please use