From 086dcfe715985447fa33f120d16a496309718ba2 Mon Sep 17 00:00:00 2001
From: Maxime Desroches <desroches.maxime@gmail.com>
Date: Tue, 30 Jul 2024 13:57:42 -0700
Subject: [PATCH] docs: fix README.md (#33142)

* md

* Update README.md

* rename

* exclude

* Update README.md
---
 docs/{README => README.md} | 22 +++++++++++++---------
 mkdocs.yml                 |  2 ++
 2 files changed, 15 insertions(+), 9 deletions(-)
 rename docs/{README => README.md} (59%)

diff --git a/docs/README b/docs/README.md
similarity index 59%
rename from docs/README
rename to docs/README.md
index a16c77253..08dd4fa8b 100644
--- a/docs/README
+++ b/docs/README.md
@@ -3,20 +3,24 @@
 This is the source for [docs.comma.ai](https://docs.comma.ai).
 The site is updated on pushes to master by this [workflow](../.github/workflows/docs.yaml).
 
-## development
-```
-# install the docs dependencies
+## Development
+NOTE: Those commands must be run in the root directory of openpilot, **not /docs**
+
+**1. Install the docs dependencies**
+``` bash
 pip install .[docs]
+```
 
-cd docs/
-
-# for a development server
-mkdocs serve
-
-# build the site
+**2. Build the new site**
+``` bash
 mkdocs build
 ```
 
+**3. Run the new site locally**
+``` bash
+mkdocs serve
+```
+
 References:
 * https://www.mkdocs.org/getting-started/
 * https://github.com/ntno/mkdocs-terminal
diff --git a/mkdocs.yml b/mkdocs.yml
index 8778e2886..743b8fa1b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -2,6 +2,8 @@ site_name: openpilot docs
 repo_url: https://github.com/commaai/openpilot/
 site_url: https://docs.comma.ai
 
+exclude_docs: README.md
+
 strict: true
 docs_dir: docs
 site_dir: docs_site/