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]