Fix Sphinx 7.x compatibility and improve Getting Started docs

.gitignore

@@ -16,6 +16,7 @@ _autosave-*
 *-save.kicad_pcb
 *cache
 desktop.ini
+.DS_Store
 # Netlist files (exported from Eeschema)
 *.net
 
@@ -31,3 +32,8 @@ desktop.ini
 *.json
 *.blif
 *.asc
+
+# not publishable files
+/private/
+/.venv/
+/docs/_build/

docs/source/conf.py

@@ -64,7 +64,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -167,5 +167,5 @@
      'Miscellaneous'),
 ]
 
-def setup (app):
-    app.add_stylesheet('css/custom.css')
+def setup(app):
+    app.add_css_file('css/custom.css')

docs/source/getting_started/first_steps.rst

@@ -1,15 +1,108 @@
 First Steps
-====
-
-1. When you receive your UPduino, make sure it works properly before you proceed further! A simple way to do this is to plug the UPduino into a standard micro USB cable attached to a standard USB power supply such as a computer or a phone charger. 
-  - You should see the green LED (D1) light up and also the 3 color LED go through a Red, Blue Green sequence. 
-  - Also, if you are on a computer, you should see a new USB device called the "UPduino 3.0" show up in your list of USB devices. 
-  - The board shows up as a serial port (COMxx on windows and /dev/ttyxx on Linux and Mac).
-2. Download the toolchain of choice: Lattice Radiant and/or icestorm/apio.
-3. Download the git repository for the UPduino and go the RTL/blink_led directory.
-4. Test your toolchain installation:
-  - apio/icestorm toolchain:
-    - Type in "make" and this should create a bin file to be uploaded to the UPduino. 
-    - For Windows, you will need to install Zadig and go through the process of switching the UPduino to the libusbk driver so that iceprog can see this. An alternative is to install the iceprog tool for windows and use that for programming instead of the icestorm version, some instructions are on [this forum](https://forum.1bitsquared.com/t/official-win10-instructions-missing/73).
-    - Program the UPduino and ensure the green (D1) LED lights up and the 3 color LED starts cycling through its sequence.
-5. Fiddle with the code!
+===========
+
+This guide helps you verify that your newly delivered UPduino board is working correctly.
+
+.. image:: ../../../assets/UPduino_v3.0_front.png
+   :width: 400
+   :alt: UPduino v3.0 board
+
+What You Need
+-------------
+
+**Micro USB Data Cable**
+   The UPduino uses a **Micro USB** connector (not USB-C). Make sure you have a
+   **data cable**, not a charge-only cable. Charge-only cables will power the board
+   but won't allow communication with your computer.
+
+   .. note::
+      Micro USB was common before ~2020. If your computer only has USB-C ports
+      (common on modern Macs and laptops), you'll need a **USB-C to Micro USB cable**
+      or adapter.
+
+   How to tell the difference:
+
+   - **Data cable**: Usually thicker, often came with a phone or external drive
+   - **Charge-only cable**: Often thinner, came with cheap power banks or LED lights
+   - **When in doubt**: Try a cable that came with an Arduino, Raspberry Pi, or older Android phone
+
+Connecting the Board
+--------------------
+
+1. Connect the UPduino to your computer using the Micro USB data cable.
+
+2. **What you should see on the board:**
+
+   If your board came pre-programmed from the manufacturer:
+
+   - The green LED (D1) lights up
+   - The RGB LED (D3) cycles through Red, Blue, Green sequence
+
+   If the board was previously programmed with different firmware, the LED
+   behavior may vary. What matters is that the serial port appears (see step 3).
+
+3. **Verify the serial port in Terminal:**
+
+   The board must be connected to a computer (not just a power supply). A USB
+   power adapter without data lines will not work.
+
+   To verify the board is recognized, compare the serial ports before and after
+   connecting:
+
+   **macOS:**
+      .. code-block:: bash
+
+         # Before connecting the board:
+         ls /dev/tty.usbserial*
+         # (should show nothing or existing devices)
+
+         # After connecting the board:
+         ls /dev/tty.usbserial*
+         # A new port appears, e.g.: /dev/tty.usbserial-XXXX
+
+   **Linux:**
+      .. code-block:: bash
+
+         # Before connecting:
+         ls /dev/ttyUSB*
+
+         # After connecting:
+         ls /dev/ttyUSB*
+         # A new port appears, e.g.: /dev/ttyUSB0
+
+   **Windows:**
+      - Open Device Manager, expand "Ports (COM & LPT)"
+      - A new COM port (e.g., COM3) should appear when you connect the board
+      - You may need to install FTDI drivers on older Windows versions
+
+Troubleshooting
+---------------
+
+**No LEDs light up:**
+   - Try a different USB cable (yours might be charge-only)
+   - Try a different USB port
+   - Check if the cable is fully inserted
+
+**LEDs work but no serial port appears:**
+   - Your cable is likely charge-only, try a data cable
+   - On Windows: Install FTDI drivers from https://ftdichip.com/drivers/
+
+**macOS: "Allow" dialog for USB accessory:**
+   - Click "Allow" when macOS asks for permission to connect to the USB device
+
+Test Conditions
+---------------
+
+This guide was tested with:
+
+- **Board:** UPduino 3.1 (February 2026)
+- **OS:** macOS 26.x (Tahoe) on Apple Silicon (M-series)
+- **Cable:** USB-C to Micro USB data cable
+
+Next Steps
+----------
+
+Once your board is recognized:
+
+1. Download a toolchain: :doc:`tool_installation`
+2. Try your first project: :doc:`../tutorials/blink_led`

docs/source/index.rst

@@ -67,8 +67,8 @@ TinyVision.ai blog posts:
    :caption: Getting Started
    :hidden:
 
-   getting_started/tool_installation
    getting_started/first_steps
+   getting_started/tool_installation
    getting_started/verilog_resources
 
 .. toctree::
@@ -86,7 +86,7 @@ TinyVision.ai blog posts:
    tutorials/blink_led.rst
    tutorials/bank_voltages
    tutorials/oscillator
-   tutorials/disconnect_tricolor_led
+   tutorials/disconnect_tri_color_led
    tutorials/fpga_sram_programming
    tutorials/qspi_flash
    tutorials/tinyfpga

docs/source/introduction/introduction.rst

@@ -1,15 +1,34 @@
 Introduction
 ============
 
-The UPduino 3.0 is a highly capable device. We will get started with setting it up, and the "hello world" of this FPGA, getting an LED to blink!
+The UPduino 3.0 is a small, low-cost FPGA development board based on the
+Lattice UltraPlus ICE40UP5K. It's ideal for learning FPGA development and
+rapid prototyping.
 
+Getting Started
+---------------
 
-First Steps
------------
+1. **Verify your board works:** :doc:`../getting_started/first_steps`
 
-First things first, after ensuring your board is functioning and shows up as a USB device, the tools need to get installed. There are two paths to do:
+   Connect your UPduino via USB and verify it's recognized by your computer.
 
-- APIO or icetools (For MacOS, Linux, and Windows)
-- Lattice Radiant (Linux and Windows only)
+2. **Install the toolchain:** :doc:`../getting_started/tool_installation`
 
-To install these tools, please go to the "Tool Installation" document!
+   Choose between open-source tools (OSS-CAD-Suite/APIO) or Lattice Radiant.
+
+3. **Your first project:** :doc:`../tutorials/blink_led`
+
+   The "Hello World" of FPGAs - make an LED blink!
+
+Toolchain Options
+-----------------
+
+**Open Source (recommended for beginners):**
+   - Works on macOS, Linux, and Windows
+   - OSS-CAD-Suite or APIO
+   - Free, no license required
+
+**Lattice Radiant:**
+   - Official Lattice tools
+   - Linux and Windows only (no macOS)
+   - Free license available from Lattice