reStructuredText
UTM → Ubuntu → Sphinx → NetlifySphinx Documentation Site
This guide walks you through the full pipeline for creating a professional documentation site with Sphinx — from installing a virtual Ubuntu machine inside UTM on macOS, to publishing the finished site on Netlify via GitHub.
Every step includes Terminal commands you can copy directly into your Ubuntu session. Use the step navigator on the right to jump to any stage of the workflow.
Step 1 — Install UTM on macOS
UTM is a free, open-source virtualisation app for macOS built on QEMU. It lets you run a full Linux desktop inside a window on your Mac, with hardware acceleration and seamless file sharing.
Download UTM from utm.app (free) or the Mac App Store (paid, supports auto-updates). Homebrew users can run brew install --cask utm.
Step 2 — Create an Ubuntu VM in UTM
First, download the Ubuntu 24.04 LTS Desktop ISO from ubuntu.com. Then in UTM:
Step 3 — Install Ubuntu
Start the VM. It boots from the ISO and presents the Ubuntu installer. Choose Try or Install Ubuntu, then follow the guided steps: select language, timezone, and keyboard layout, create your username and password, and click Install Now.
After installation completes and the VM reboots, eject the ISO in UTM under VM Settings → CD/DVD so it doesn't boot from the installer again.
Step 4 — Configure Ubuntu
Open the Terminal (Ctrl+Alt+T) and run a full system update, then install the Python and Git tools you'll need throughout this guide.
Step 5 — Set Up UTM Shared Directory
UTM exposes a WebDAV server at http://localhost:9843 so you can move files between macOS and Ubuntu — ideal for copying logos, fonts, and other static assets into your Sphinx project.
In Ubuntu's Files app, go to Other Locations → Connect to Server and type dav://localhost:9843. Alternatively, mount it from the Terminal using davfs2.
Step 6 — Prepare the Python Virtual Environment
Ubuntu 24.04 and later protect the system Python with PEP 668, which means pip install at the system level is blocked. The solution is to create an isolated virtual environment (venv) for each project.
The venv gives you a private python and pip that install packages only inside your project folder — no root access needed, no system-wide side-effects.
Step 7 — Install Sphinx and Extensions
With the venv active, install the following packages:
sphinxCore documentation enginesphinx-rtd-themeRead the Docs visual themesphinxcontrib-httpdomainHTTP API method documentationsphinxcontrib-mermaidMermaid diagram support in .rst filessphinx-autobuildLive-reload server for local preview (optional)Step 8 — Run sphinx-quickstart
sphinx-quickstart is an interactive wizard that generates the initial project skeleton. The most important prompt asks whether to keep the source and build directories separate — always choose yes.
After the wizard completes, the project contains source/conf.py (the main config file), source/index.rst (the root table of contents), and a Makefile that drives the build.
Step 9 — Build and Preview
Run make html from the project root. Sphinx reads every .rst file in source/, applies your theme, and writes a complete static website into build/html/. Open index.html directly in a browser, or serve it with Python's built-in HTTP server for live testing.
Step 10 — Add File Assets
Place your logo and any custom CSS inside source/_static/. Then reference them in source/conf.py using the html_logo and html_css_files settings. Rebuild with make html to see the changes.
Step 11 — Push to GitHub
Initialise a Git repository in your project, commit your source files, and push to GitHub. Since August 2021, GitHub no longer accepts account passwords over HTTPS — use a Personal Access Token (PAT) instead. Generate one at github.com → Settings → Developer settings → Personal access tokens with the repo scope, then paste it when Git prompts for a password.
Always commit a .gitignore that excludes build/ and venv/ — these are generated artefacts and should never be tracked.
Step 12 — Deploy to Netlify
Connect your GitHub repo to Netlify (netlify.com → Add new site → Import an existing project). Set the build command and publish directory as shown in the right panel. Netlify will install your dependencies, run Sphinx, and publish the output on every push to main.
Commit a requirements.txt listing your Sphinx packages so the Netlify build environment knows exactly what to install — this prevents version drift between local and CI builds.
Live result: sphinxdoks.netlify.app
Steps
Terminal commands — Install UTM on macOS
# Install via Homebrew Cask
brew install --cask utm# Confirm UTM is recognised by macOS
ls /Applications/UTM.appPro tip
Always activate the venv before working on your project: source venv/bin/activate. Your prompt will show (venv) as a reminder. Run deactivate when you're done.