Add a tutorial introduction.

.github/workflows/build_docs.yaml

@@ -18,7 +18,7 @@ jobs:
     - name: Install dependencies and local packages
       run: python -m pip install sphinx pydata-sphinx-theme
     - name: Build HTML documentation with Sphinx
-      run: make html
+      run: make html SPHINXOPTS="-W --keep-going -n"
       working-directory: docs
     - uses: actions/upload-pages-artifact@v3
       with:

.github/workflows/check_docs.yaml

@@ -16,7 +16,7 @@ jobs:
     - name: Install dependencies and local packages
       run: python -m pip install sphinx pydata-sphinx-theme
     - name: Build HTML documentation with Sphinx
-      run: make html
+      run: make html SPHINXOPTS="-W --keep-going -n"
       working-directory: docs
     - uses: actions/upload-artifact@v4
       with:

README.rst

@@ -4,6 +4,14 @@ Ultimo
 Ultimo is an interface framework for micropython built around asynchronous
 iterators.
 
+- `Documentation <https://github.io/unital/ultimo>`_
+- `Tutorial <https://github.io/unital/ultimo/user_guide/tutorial.html>`_
+- `User Guide <https://github.io/unital/ultimo/user_guide.html>`_
+- `Examples <https://github.io/unital/ultimo/user_guide/examples.html>`_
+
+Description
+-----------
+
 Ultimo allows you to implement the logic of a micropython application
 around a collection of asyncio Tasks that consume asynchronous iterators.
 This is compared to the usual synchronous approach of having a single main

docs/source/conf.py

@@ -51,13 +51,13 @@
         },
     ],
     "icon_links_label": "Quick Links",
-    "default_mode": "dark",
 }
 html_context = {
     "github_user": "unital",
     "github_repo": "ultimo",
     "github_version": "main",
     "doc_path": "docs",
+    "default_mode": "dark",
 }
 
 # -- Options for autodoc -----------------------------------------------------

docs/source/index.rst

@@ -20,15 +20,15 @@ activity, so a user interaction, like changing the value of a potentiometer or
 polling a button can happen in milliseconds, while a clock or temperature
 display can be updated much less frequently.
 
-The ``ultimo`` library provides classes that simplify this paradigm.
+The :py:mod:`ultimo` library provides classes that simplify this paradigm.
 There are classes which provide asynchronous iterators based around polling,
 interrupts and asynchronous streams, as well as intermediate transforming
 iterators that handle common tasks such as smoothing and de-duplication.
 The basic Ultimo library is hardware-independent and should work on any
 recent micropython version.
 
-The ``ultimo_machine`` library provides hardware support wrapping
-the micropython ``machine`` module and other standard library
+The :py:mod:`ultimo_machine` library provides hardware support wrapping
+the micropython :py:mod:`machine`` module and other standard library
 modules.  It provides sources for simple polling of, and interrupts from, GPIO
 pins, polled ADC, polled RTC, and interrupt-based timer sources.
 

docs/source/user_guide.rst

@@ -15,6 +15,7 @@ This is the user-guide for Ultimo.
 
    user_guide/introduction.rst
    user_guide/installation.rst
+   user_guide/tutorial.rst
    user_guide/core_classes.rst
    user_guide/machine_classes.rst
    user_guide/display_classes.rst

docs/source/user_guide/installation.rst

@@ -10,7 +10,29 @@ we would like to add ``mip`` and better stub file support.
 Installation
 ------------
 
-If you want to experiment with Ultimo on a Raspberry Pi Pico, there is a
+Ultimo can be installed from github via :py:mod:`mip`.  For most use-cases
+you will probably want to install :py:mod:`ultimo_machine` which will also
+insatll the core :py:mod:`ultimo` package:
+
+..  code-block:: python-console
+
+    >>> mip.install("github:unital/ultimo/src/ultimo_machine/package.json")
+
+or using :py:mod:`mpremote`:
+
+..  code-block:: console
+
+    mpremote mip install github:unital/ultimo/src/ultimo_machine/package.json
+
+You can separately install :py:mod:`ultimo_display` from
+``github:unital/ultimo/src/ultimo_display/package.json`` and if you just
+want the core :py:mod:`ultimo` without any hardware support, you can install
+``github:unital/ultimo/src/ultimo/package.json``.
+
+Development Installation
+------------------------
+
+To simplify the development work-cycle with actual hardware, there is a
 helper script in the ci directory which will download the files onto the
 device.  You will need an environment with ``mpremote`` and ``click``
 installed.  For example, on a Mac/Linux machine: