Cleanup of documentation

[krisgesling]

Description

Improve documentation including standardizing docstrings and address warnings raised by the Sphinx readthedocs builder, as well as fixing up issues in CLI client.

• We currently go by the Google Python Docstrings Style Guide which uses Args: rather than Arguments:. This has been inconsistently used throughout the code base so this modifies them all to be the standard.
• Fixed heading underlines to silence warnings
• Added missing lines to silence warnings and aid readability
• Improved formatting of particular items eg mycroft.MycroftSkill.get_response had missing content, and now provides highlighted examples.
• Fixed capitalization of "Skills" in the CLI help info
• Fixed incorrect colors on Log Output Legend
• Fixed incorrect keyboard shortcuts for next and previous utterances in CLI
• ran autopep8 on touched files to address auto-format.

How to test

source .venv/bin/activate
cd doc
make html

Also check the CLI client

Contributor license agreement signed?

• CLA (Whether you have signed a CLA - Contributor Licensing Agreement

[pep8speaks]

Hello @krisgesling! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2021-05-11 05:42:51 UTC

[devops-mycroft]

Voight Kampff Integration Test Succeeded (Results)

[forslund]

Nice work. Looks very clean and get_response() looks great!

I do however still get a bunch of warnings:
/home/ake/projects/python/mycroft-core/mycroft/util/parse.py:docstring of mycroft.util.parse.normalize:10: WARNING: Block quote ends without a blank line; unexpected unindent.

Are these intended to be left in?

IMO the auto-pep8 should be run in a separate commit but not a big deal here.

EDIT:
The warnings seems to be fixable by adding blank lines between the different section (after first line summary, after body and after argument list) See here

EDIT2: The commonIOT skill also has an undefined type-hint, I don't know very much of type-hints so I'm not sure what's the best way to handle that.

EDIT3: it wasn't the type-hint that was the issue, rather the _ after request triggering some weird internal warning. See here

[krisgesling]

Indeed - need to PEP8 the whole repo so it doesn't catch you when you're updating something completely separate...
I might at least remove text_client.py and do that separately given the auto-format changes are quite extensive.

The remaining warnings for parse and format docstrings should no longer exist in this repo with the inclusion of LF v0.4.1.

Nice find on the underscore issue!

[forslund]

Then they were left intentionally. Feel free to add the common_iot_skill fix. And merge away when the PEP-8 line length issues have been fixed :)

[krisgesling]

hmm soz... I probably should have done the PEP8 in a separate commit while I was at it, but I'm a terrible person 😈

[devops-mycroft]

Voight Kampff Integration Test Failed (Results).
Mycroft logs are also available: skills.log, audio.log, voice.log, bus.log, enclosure.log

[krisgesling]

Timer Skill you are drunk! :P

[forslund]

Timer skill is definitely the black sheep among the skills. Always the drunk one and always the loudest :P

[devops-mycroft]

Voight Kampff Integration Test Succeeded (Results)

[chrisveilleux]

Hard to argue with this change... oh I crack myself up. Nice work Gez.