Fix and test docs on Windows (#2262)

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

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 04b25cf2a16a61edc255bf5bbc78fed5cfb9cbc7..5689d2887c4fdf5ac70a44e3b15808b657dea223 100644 (file)
--- 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 de326e4ee7b4747b4bc1116b574740ef92ca7887..0a87fd1dbf40e119d083157d9205f2bdbc1fca7b 100644 (file)
--- 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 (symlink)
index 3234d6e079296960c9478d789bc66fb5b81af819..0000000000000000000000000000000000000000
--- 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 (file)
index 0000000000000000000000000000000000000000..21b0e1a1f5b89ac9ea6dbbb200aaae12988f0155
--- /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 (symlink)
index cf547089dc1f43211a11dafea96e8332884bb5d3..0000000000000000000000000000000000000000
--- 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 (file)
index 0000000000000000000000000000000000000000..e5f67e755d362f8913250e13069955a0196c62a8
--- /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 15adb5df7a1c6b6baa3ed47bd318e5150a0c4ad0..55d0fa99dc6c2ce290fe0c7ec9b1b31ae7590bf5 100644 (file)
--- 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"