# How to Set Up Beautiful Documentation for Your Python Project with Read the Docs, Sphinx, Furo, and MyST-Parser

If you're building a Python project, great documentation can make all the difference for your users — and for your future self! 

In this guide, I'll show you how to create beautiful, modern documentation for your project using:

✅ [**Read the Docs**](https://readthedocs.io) — free hosting for your docs  
✅ [**Sphinx**](https://www.sphinx-doc.org/en/master/) — powerful documentation generator  
✅ [**Furo**](https://pradyunsg.me/furo/) — sleek, responsive Sphinx theme  
✅ [**MyST-Parser**](https://myst-parser.readthedocs.io/) — Markdown support for Sphinx  

By the end of this tutorial, you’ll have professional-looking documentation for your Python project that automatically builds and updates when you push to GitHub.

---

## ✨ Why this stack?

- **Read the Docs**: free, automated hosting and builds
- **Sphinx**: mature, flexible tool for Python docs (and more)
- **Furo**: modern, clean theme that works great on all devices
- **MyST-Parser**: write your docs in **Markdown** (instead of reStructuredText)

---

## 🗂️ Project Structure

Here’s the structure we’re aiming for:

```
myproject/
├── mypackage/               # Your Python code
├── docs/
│   ├── source/
│   │   ├── conf.py          # Sphinx config
│   │   ├── index.md         # Your doc index (Markdown!)
│   │   ├── getting_started.md
│   │   ├── usage.md
│   ├── requirements.txt     # Doc dependencies
├── .readthedocs.yml         # Read the Docs build config
├── pyproject.toml / setup.py
├── README.md
└── requirements.txt         # (optional for project deps)
```

---

## 🔧 Prerequisites

- A Python project (package or scripts)
- GitHub / GitLab / Bitbucket repo — required for Read the Docs
- Python 3.8+ installed

---

## 🏗️ Step 1: Install Sphinx and Dependencies

First, set up a **virtual environment** (optional, but recommended):

```bash
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate    # Windows
```

Now install:

```bash
pip install sphinx furo myst-parser
```

---

## 📚 Step 2: Initialize Sphinx

In your project root:

```bash
sphinx-quickstart docs
```

Answer the prompts:

- Separate source and build dirs: **Yes**
- Project name, author, version: your project info
- Create Makefile: **Yes**

Now you’ll have:

```
docs/
├── build/        # Will be generated
├── source/
│   ├── _static/
│   ├── _templates/
│   ├── conf.py
│   ├── index.rst
└── Makefile / make.bat
```

---

## ⚙️ Step 3: Configure `conf.py`

Edit `docs/source/conf.py`.

### 1️⃣ Add extensions:

```python
extensions = [
    "myst_parser",               # Markdown support
    "sphinx.ext.autodoc",        # Auto API docs from docstrings
    "sphinx.ext.napoleon",       # Google/NumPy docstring support
    "sphinx.ext.viewcode",       # Link to highlighted source code
]
```

### 2️⃣ Set the Furo theme:

```python
html_theme = "furo"
```

### 3️⃣ Allow Markdown and reStructuredText:

```python
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}
```

### 4️⃣ Add your project path (optional but useful for autodoc):

```python
import os
import sys
sys.path.insert(0, os.path.abspath('../../'))  # Adjust as needed
```

---

## 📝 Step 4: Write Your Docs in Markdown

You can now write your docs using **Markdown**!

Replace `index.rst` with `index.md` (you can delete the `.rst`).

Example `docs/source/index.md`:

```markdown
# My Project

Welcome to the documentation for **My Project**!

## Contents

```{toctree}
:maxdepth: 2
:caption: Contents

getting_started.md
usage.md
api_reference.md
```
```

Then create:

- `getting_started.md`
- `usage.md`
- `api_reference.md`

Example `getting_started.md`:

```markdown
# Getting Started

Install My Project:

```bash
pip install myproject
```
```

---

## 🏃 Step 5: Build Locally

You can test the docs locally:

```bash
cd docs
make html
```

Open: `docs/build/html/index.html` in your browser.

---

## ☁️ Step 6: Set Up Read the Docs

### 1️⃣ Push your project to GitHub (or GitLab/Bitbucket).

### 2️⃣ Add `.readthedocs.yml`

At your project root, create `.readthedocs.yml`:

```yaml
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"  # or your version

python:
  install:
    - requirements: docs/requirements.txt

sphinx:
  configuration: docs/source/conf.py
```

### 3️⃣ Create `docs/requirements.txt`

```txt
sphinx
furo
myst-parser
```

---

## 🚀 Step 7: Connect to Read the Docs

1. Go to [https://readthedocs.io](https://readthedocs.io).
2. Sign in with GitHub.
3. Import your project.
4. It will detect `.readthedocs.yml` — no UI config needed!
5. Trigger a build.
6. Your docs will be live at:

```
https://yourproject.readthedocs.io
```

---

## 🔍 Summary

✅ Beautiful, responsive docs with **Furo**  
✅ Write in **Markdown** with MyST-Parser  
✅ Auto builds and deploys on **Read the Docs**  
✅ Version-controlled with `.readthedocs.yml`  

---

## 💡 Bonus Tips

- Add **autodoc** and **API reference** by writing `.rst` files or using [sphinx-apidoc](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html).
- Add a **project logo** in `conf.py`:

```python
html_logo = "_static/logo.png"
```

- Customize Furo with:

```python
html_theme_options = {
    "light_logo": "logo.png",
    "dark_logo": "logo_dark.png",
}
```

---

## Final Thoughts

If you follow this setup, you’ll have modern, professional documentation that:

✅ looks great  
✅ updates automatically  
✅ works for open source and private projects  

I use this exact setup on many projects — highly recommended!

---

👉 Do you have questions about using Sphinx, MyST, or Read the Docs?  
👉 Want to see how to generate an **automatic API reference**?

Comment below and I’ll write a follow-up post!

---

If you enjoyed this post, follow me for more **Python** & **developer tooling** tips! 🚀