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 — free hosting for your docs
✅ Sphinx — powerful documentation generator
✅ Furo — sleek, responsive Sphinx theme
✅ MyST-Parser — 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):

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

Now install:

pip install sphinx furo myst-parser

---

📚 Step 2: Initialize Sphinx

In your project root:

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:

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:

html_theme = "furo"

3️⃣ Allow Markdown and reStructuredText:

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

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

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:

# 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:

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

sphinx
furo
myst-parser

---

🚀 Step 7: Connect to Read the Docs

1. Go to 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.
• Add a project logo in conf.py:

html_logo = "_static/logo.png"

• Customize Furo with:

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! 🚀