From 1b43f957175d1182e0b048d3b07f0f46123e6466 Mon Sep 17 00:00:00 2001
From: Eric Bouchut <ebouchut@gmail.com>
Date: Mon, 30 Sep 2024 21:45:24 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20how=20to=20install=20and?=
 =?UTF-8?q?=20preview=20trio-docs=20locally?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/README.md b/README.md
index 92ada9f9..4152cde3 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,53 @@
 Repository for [Trio documentation (under development)](https://docs.diy-trio.org)
 
+
+## Install
+
+- [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) this project
+- Install *Python*  3
+  Review [Properly Installing Python](http://docs.python-guide.org/en/latest/starting/installation/) for help on getting *Python* installed.
+- Install a Python Virtual Environment.  
+  In this example, I use [`venv`](https://realpython.com/python-virtual-environments-a-primer/#how-can-you-work-with-a-python-virtual-environment), but use whichever you prefer.  
+  
+```shell
+cd trio-docs # cd into the folder where you cloned this repository
+
+# Creates a virtual environment using Python 3 in the venv folder  
+python3 -m venv venv 
+
+# Activate the virtual environment
+# Run the next line **each time** you start a new shell window/tab
+source venv/bin/activate
+
+# Make sure you are in the folder where you cloned this repository, if not:
+# cd trio-docs 
+
+# Install the project's required packages
+python -m pip install -r dev-requirements.txt
+pip-compile
+python -m pip install -r requirements.txt
+```
+
+## Run
+
+Once [installed](#install), you can preview the doc locally as you edit.
+
+### Preview Changes Locally
+
+To preview your work as you edit:
+
+- Run this command in a separate terminal window/tab and do not interrupt it:
+  ```shell
+  # cd trio-docs # cd where you cloned this repository
+
+  # sphinx-build -M html EN/ _build/
+  sphinx-autobuild docs/EN docs/_build/html
+  ```
+  This builds the site and runs a local Web browser on:   
+    http://127.0.0.1:8000
+  It also rebuilds the site when you change a file and hot refreshes the browser so that you can see the changes.
+  
+
 ## Tips & Tricks
 
 > [!NOTE]