Develop Docs Locally

Develop Docs Locally#

If you are familiar with the basics of a local development environment, you can set one up to develop documentation locally - that is, on your machine rather than waiting for the automated build on GitHub.

Prerequisites#

In this How-To guide, we assume that you have the following:

A Mac or Linux environment
Familiarity with the command line (terminal application), or the desire to learn!

Set Up Your Environment#

On a Mac, first install homebrew using the command line (“Terminal” application on a Mac):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Python, using the version specified in .readthedocs.yaml:

# On Mac
brew install python3.12 # Insert proper version here

Install Git:
```
# On Mac
brew install git
```
Create a directory to hold your openedx code (I call it openedx but you can call it anything) and switch to that directory:
```
mkdir openedx
cd openedx
```
Using the command line, clone the repo locally, into a directory you use to write Open edX code (for example, a directory called openedx):
```
git clone git@github.com:openedx/docs.openedx.org.git
```
Switch into the docs.openedx.org folder:
```
cd docs.openedx.org
```

Create a new Virtualenv for docs development:

python3.12 -m venv .venv # Use proper Python version here

Activate the virtual environment:
```
source .venv/bin/activate
```

Writing Documentation Locally#

Set up a local code editor. VS code (download link) is recommended as it is easy to use.
Set up your code editor to read from your openedx folder.
Write some docs!!

Build and Test Documentation Locally#

First, ensure you are working within your docs virtual environment, and run the requirements script:

cd openedx # or the folder where you cloned the docs.openedx.org repo
cd docs.openedx.org
source .venv/bin/activate
make requirements

To build documentation inside the root folder, run:
```
make clean
make html
```
Sphinx should build the HTML files locally. If there are errors, you will need to address them. Once the HTML successfully builds (“The HTML pages are in build/html.”), To serve the docs locally, run:
```
make serve_docs
```

Once this process is running, you can view the docs in your browser by navigating to http://127.0.0.1:8000

Note

This is a background process, and it will continue updating the docs as you edit them. However if you make substantive changes, such as adding cross-references, intersphinx references, or lines to links.txt, you should kill the process and run make clean/ make html again. We’re fortunate to have a lot of docs - but this means that make html can take 3-4 minutes to run.

You should ensure the documentation builds with no errors or warnings when submitting a pull request. Occasionally the docs build on the pull request will contain errors that weren’t caught locally, so do check the upstream build before requesting reviews. If you’re stumped by an error, please tag the docs maintainer team on your pull request and ask for help!

Making a Pull Request#

Follow the Process for Contributing Code.

The gh CLI tool is a great way to interact with GitHub on the command line. You can also interact with GitHub via your code editor (for example, Using Git with VS Code).

Review Date	Working Group Reviewer	Release	Test situation
2025-11-15	sarina	Ulmo	Pass