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

@@ -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/

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]
 * [email protected]
 
-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
   <img width="15%" src="https://aiyprojects.withgoogle.com/static/images/icons/aiy-circular-logo.svg">
 </p>
 
-[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

CHANGES.md → 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
+[github-releases]: https://github.com/google/aiyprojects-raspbian/releases
+[system-updates]: HACKING.html

HACKING.md → 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/

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 <CHANGES>
+   System updates <HACKING>
+   Source code (GitHub) <https://github.com/google/aiyprojects-raspbian>
+
 API indices
 --------------
 
 * :ref:`Full index <genindex>`
 * :ref:`Module index <modindex>`
-
-Source code is
-`on GitHub <https://github.com/google/aiyprojects-raspbian>`_.