remove duplication between README and Documentation

Also move badges to the top of README where they can be
stripped away more easily when generating the project
description for PyPI.

README.rst

@@ -1,12 +1,16 @@
-=====================
-py-esp32-ulp
-=====================
+.. start-badges
 
 .. image:: ../../actions/workflows/run_tests.yaml/badge.svg
    :height: 20px
    :target: ../../actions/workflows/run_tests.yaml
    :alt: Build Status
 
+.. end-badges
+
+=====================
+py-esp32-ulp
+=====================
+
 py-esp32-ulp is an assembler toolchain for the ESP32 ULP (Ultra Low-Power)
 Co-Processor, written in MicroPython.
 
@@ -16,6 +20,8 @@ ULP machine code binary, directly on the ESP32 microcontroller.
 This is intended as an alternative approach to assembling such programs using
 the binutils-esp32ulp toolchain from Espressif on a development machine.
 
+It can also be useful in cases where binutils-esp32ulp is not available.
+
 
 Features
 --------
@@ -49,9 +55,6 @@ To get going run the following directly on the ESP32:
 The `counter.py </examples/counter.py>`_ example shows how to assemble code, load
 and run the resulting binary and exchange data between the ULP and the main CPU.
 
-You can also try the `blink.py </examples/blink.py>`_ example, which shows how to
-let the ULP blink an LED.
-
 
 Documentation
 -------------

docs/index.rst

@@ -1,47 +1,13 @@
 py-esp32-ulp Documentation
 ==========================
 
-py-esp32-ulp is an assembler toolchain for the ESP32 ULP (Ultra Low-Power)
-Co-Processor, written in MicroPython.
-
 .. contents:: Table of Contents
 
 
-What is it useful for?
-----------------------
-
-py-esp32-ulp can translate small assembly language programs to a
-loadable/executable ULP machine code binary, directly on the ESP32
-microcontroller.
-
-This is intended as an alternative approach to assembling such programs using
-the binutils-esp32ulp toolchain from Espressif on a development machine.
-
-It can also be useful in cases where binutils-esp32ulp is not available.
-
-
-Features
+Overview
 --------
 
-The following features are supported:
-
-* the entire `ESP32 ULP instruction set <https://esp-idf.readthedocs.io/en/latest/api-guides/ulp_instruction_set.html>`_
-* constants defined with ``.set``
-* constants defined with ``#define``
-* expressions in assembly code and constant definitions
-* RTC convenience macros (e.g. WRITE_RTC_REG)
-* many ESP32 ULP code examples found on the web will work unmodified
-
-
-Limitations
------------
-
-Currently the following are not supported:
-
-* assembler macros using ``.macro``
-* preprocessor macros using ``#define A(x,y) ...``
-* including files using ``#include``
-* ESP32-S2 (not binary compatible with the ESP32)
+`README.rst </README.rst>`_ gives a general overview of this project.
 
 
 Installation
@@ -170,6 +136,17 @@ found as part of Arduino/ESP-IDF projects.
 The preprocessor and how to use it is documented here: `Preprocessor support </docs/preprocess.rst>`_.
 
 
+Limitations
+-----------
+
+Currently the following are not supported:
+
+* assembler macros using ``.macro``
+* preprocessor macros using ``#define A(x,y) ...``
+* including files using ``#include``
+* ESP32-S2 (not binary compatible with the ESP32)
+
+
 Testing
 -------