From 2d02f290eb7e66d995cf5c356446067fe2eaa476 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Wed, 26 May 2021 11:46:16 -0400
Subject: [PATCH] Fix and test docs on Windows

There's some weird interaction between Click and
sphinxcontrib-programoutput on Windows that leads to an encoding error
during the printing of black-primer's help text.

Also symlinks aren't well supported on Windows so let's just use
includes which actually work because we now use MyST :D
---
 .github/workflows/doc.yml | 11 +++++++----
 CHANGES.md                |  1 +
 docs/authors.md           |  4 +++-
 docs/change_log.md        |  4 +++-
 docs/conf.py              |  8 +++++++-
 5 files changed, 21 insertions(+), 7 deletions(-)
 mode change 120000 => 100644 docs/authors.md
 mode change 120000 => 100644 docs/change_log.md

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 04b25cf2a16..5689d2887c4 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -11,14 +11,17 @@ jobs:
       github.event_name == 'push' || github.event.pull_request.head.repo.full_name !=
       github.repository
 
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set up Python 3.9
+      - name: Set up latest Python
         uses: actions/setup-python@v2
-        with:
-          python-version: 3.9
 
       - name: Install dependencies
         run: |
diff --git a/CHANGES.md b/CHANGES.md
index de326e4ee7b..0a87fd1dbf4 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,6 +25,7 @@
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
 - Add new Frequently Asked Questions page (#2247)
+- Fix encoding + symlink issues preventing proper build on Windows (#2262)
 
 ## 21.5b1
 
diff --git a/docs/authors.md b/docs/authors.md
deleted file mode 120000
index 3234d6e0792..00000000000
--- a/docs/authors.md
+++ /dev/null
@@ -1 +0,0 @@
-../AUTHORS.md
\ No newline at end of file
diff --git a/docs/authors.md b/docs/authors.md
new file mode 100644
index 00000000000..21b0e1a1f5b
--- /dev/null
+++ b/docs/authors.md
@@ -0,0 +1,3 @@
+```{include} ../AUTHORS.md
+
+```
diff --git a/docs/change_log.md b/docs/change_log.md
deleted file mode 120000
index cf547089dc1..00000000000
--- a/docs/change_log.md
+++ /dev/null
@@ -1 +0,0 @@
-../CHANGES.md
\ No newline at end of file
diff --git a/docs/change_log.md b/docs/change_log.md
new file mode 100644
index 00000000000..e5f67e755d3
--- /dev/null
+++ b/docs/change_log.md
@@ -0,0 +1,3 @@
+```{include} ../CHANGES.md
+
+```
diff --git a/docs/conf.py b/docs/conf.py
index 15adb5df7a1..55d0fa99dc6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,8 +12,10 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-from pathlib import Path
+
+import os
 import string
+from pathlib import Path
 
 from pkg_resources import get_distribution
 
@@ -29,6 +31,10 @@ def make_pypi_svg(version: str) -> None:
         f.write(svg)
 
 
+# Necessary so Click doesn't hit an encode error when called by
+# sphinxcontrib-programoutput on Windows.
+os.putenv("pythonioencoding", "utf-8")
+
 # -- Project information -----------------------------------------------------
 
 project = "Black"