From 42d35cc1ef0a0f395909b91262973e9e2643927f Mon Sep 17 00:00:00 2001 From: scottamain Date: Thu, 27 Dec 2018 14:25:55 -0800 Subject: [PATCH] Add more docs to the RTD site; moving them into the docs/ path. Includes misc editing for the root README and HACKING docs. Leave CONTRIBUTING as a GitHub page at root; link to GitHub from the RTD nav. Change-Id: I21394faaf2c459d0ac2ac3cdab7dc4a0958cc80e --- CONTRIBUTING.md | 8 ++--- README.md | 55 ++++++++++++++++++++++------------- CHANGES.md => docs/CHANGES.md | 10 +++++-- HACKING.md => docs/HACKING.md | 17 ++++++----- docs/index.rst | 11 +++++-- 5 files changed, 64 insertions(+), 37 deletions(-) rename CHANGES.md => docs/CHANGES.md (88%) rename HACKING.md => docs/HACKING.md (87%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index addcd6c6..fa7b623f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ -# Contributions +# Contributing -We'd love to accept your patches and contributions to this project. There are -just a few small guidelines you need to follow. +We'd love to accept your patches and contributions to this project. +There are just a few small guidelines you need to follow. ## Scope of Contributions @@ -31,4 +31,4 @@ use GitHub pull requests for this purpose. Consult [GitHub Help] for more information on using pull requests. [hackster.io]: https://www.hackster.io/ -[GitHub Help]: https://help.github.com/articles/about-pull-requests/ +[GitHub Help]: https://help.github.com/articles/about-pull-requests/ \ No newline at end of file diff --git a/README.md b/README.md index c90f745d..546a95c8 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,44 @@ # AIY Projects -## Overview - -This repository contains an easy-to-use API for the [AIY Vision Kit][aiy-vision] -and [AIY Voice Kit][aiy-voice]. Have a look at [example code][aiy-github-examples] -to see how both kits can be used. Comprehensive documentation is at the -[AIY Projects Site][aiy-site]. - -If you're using Raspbian instead of Google's provided image, read -[HACKING.md] for information on getting started. - -For returning users. The code for all AIY kits is in the `aiyprojects` branch, +This repository contains an easy-to-use Python API for the [AIY Vision Kit][aiy-vision] +and [AIY Voice Kit][aiy-voice]. The code for all AIY kits is in the `aiyprojects` branch, and is included in images starting with `aiyprojects-2017-12-18.img`. The previous `voicekit` branch contains code just for the Voice Kit, and the `master` branch contains the original deprecated `Voice Recognizer` demo. -## Support +## Documentation + +If you're just getting started with the Vision or Voice kit, see the +assembly guide and other maker guides at [aiyprojects.withgoogle.com]. + +If you just need the Python API reference, see [aiyprojects.readthedocs.io]. +Also have a look at the [example code][aiy-github-examples]. + +If you need to update your kit's system image (whether you're using Google's provided image or +you're starting with Raspbian), read the [system updates guide][hacking]. -If you're having trouble assembling your kit or running the demos, you can try +## Releases +* [Image downloads][downloads] +* [Change log][changelog] + +## Bugs & Support + +If you've found a bug, please [review the known issues and report a new one][issues]. + +If you've fixed a bug yourself, please send us a pull request! +For details, read [CONTRIBUTING.md]. + +If you're having trouble assembling your kit or running the demos, try the following links: + +* [AIY Help docs][help-docs] * [AIY Forums][aiy-forums] * [AIY Stack Overflow][aiy-stack-overflow] * [AIY GitHub Issues][aiy-github-issues] * support-aiyprojects@google.com -If you've found a bug and fixed it yourself, please send us a pull request! -Check [CONTRIBUTING.md] for details. - -If you've found a problem with the Assistant (for example, crashes in the -library or incorrect responses), you can try +If you've found a problem with the Assistant API (for example, it crashes +or provides incorrect responses), try the following: * [Assistant G+ community][assistant-google-plus] * [Assistant Stack Overflow][assistant-stack-overflow] @@ -40,13 +50,18 @@ library or incorrect responses), you can try

-[HACKING.md]: HACKING.md +[hacking]: https://aiyprojects.readthedocs.io/en/latest/HACKING.html [CONTRIBUTING.md]: CONTRIBUTING.md +[downloads]: https://github.com/google/aiyprojects-raspbian/releases +[changelog]: https://aiyprojects.readthedocs.io/en/latest/CHANGES.html -[aiy-site]: https://aiyprojects.withgoogle.com/ +[aiyprojects.withgoogle.com]: https://aiyprojects.withgoogle.com +[aiyprojects.readthedocs.io]: https://aiyprojects.readthedocs.io [aiy-vision]: https://aiyprojects.withgoogle.com/vision/ [aiy-voice]: https://aiyprojects.withgoogle.com/voice/ +[issues]: https://github.com/google/aiyprojects-raspbian/issues +[help-docs]: https://aiyprojects.withgoogle.com/help [aiy-forums]: https://www.raspberrypi.org/forums/viewforum.php?f=114 [aiy-stack-overflow]: https://stackoverflow.com/questions/tagged/google-aiy [aiy-github-issues]: https://github.com/google/aiyprojects-raspbian/issues diff --git a/CHANGES.md b/docs/CHANGES.md similarity index 88% rename from CHANGES.md rename to docs/CHANGES.md index 89af5ef9..2a3a39cf 100644 --- a/CHANGES.md +++ b/docs/CHANGES.md @@ -1,6 +1,9 @@ -# Changelog +# Change log -All SD card images can be found at [releases][github-releases] page. +This page describes the changes in each release. + +To update your kit, see the [system updates guide][system-updates]. +All system images can be downloaded from the [GitHub releases page][github-releases]. ## AIY Kits Release 2018-11-16 @@ -66,4 +69,5 @@ Compatible with Voice HAT and Vision Bonnet. Compatible with Voice HAT. -[github-releases]: https://github.com/google/aiyprojects-raspbian/releases \ No newline at end of file +[github-releases]: https://github.com/google/aiyprojects-raspbian/releases +[system-updates]: HACKING.html \ No newline at end of file diff --git a/HACKING.md b/docs/HACKING.md similarity index 87% rename from HACKING.md rename to docs/HACKING.md index 103e823e..ead8e4b6 100644 --- a/HACKING.md +++ b/docs/HACKING.md @@ -1,16 +1,18 @@ -# Setting up the image - -## Overview +# System updates We periodically update the SD card image that supports both the Vision Kit and Voice Kit. Each release is based on [Raspbian][raspbian], with a few customizations, and they are tested on various Raspberry Pi models. -To update your system image, download the latest `.img.xz` file -[from our releases page][github-releases]. Once downloaded, -[write the image to your SD card][image-flash], and you're good to go! +You can flash the latest system image for your kit as follows: + +1. Download the latest `.img.xz` file from the [releases page on GitHub][github-releases]. (For release details, see the [Change log][changelog].) +1. Use an adapter to connect your MicroSD card to your computer. +1. Use a program such as [balenaEtcher](https://www.balena.io/etcher/) to flash the `.img.xy` file onto your MicroSD card. (balenaEtcher is free and works on Windows, Mac OS, and Linux.) + +When flashing is done, put the MicroSD card back in your kit and you're good to go! -If you prefer to setup Raspbian yourself, follow the steps below. +If you prefer to update an existing Raspbian image yourself, follow the steps below. ## AIY Debian Package Repo @@ -181,6 +183,7 @@ To access the cloud services you need to register a project and generate credentials for cloud APIs. This is documented in the [setup instructions][aiy-voice-setup] on the webpage. +[changelog]: CHANGES.html [raspbian]: https://www.raspberrypi.org/downloads/raspbian/ [image-flash]: https://www.raspberrypi.org/documentation/installation/installing-images/ [aiy-models]: https://aiyprojects.withgoogle.com/models/ diff --git a/docs/index.rst b/docs/index.rst index 63571dc4..292704e7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,11 +37,16 @@ assembly guides and makers guides, go to aiy.voice.audio aiy.voice.tts +.. toctree:: + :caption: Other docs + :maxdepth: 2 + + Change log + System updates + Source code (GitHub) + API indices -------------- * :ref:`Full index ` * :ref:`Module index ` - -Source code is -`on GitHub `_. \ No newline at end of file