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

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
 

docs/authors.md

@@ -0,0 +1,3 @@
+```{include} ../AUTHORS.md
+
+```

docs/change_log.md

@@ -0,0 +1,3 @@
+```{include} ../CHANGES.md
+
+```

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"