Sphinx on Windows
kyrab at mail.ru
Mon Oct 26 14:40:20 UTC 2015
The Sphinx + GHC HEAD on Windows story is somewhat complicated.
Incidentally I've just managed to get it all working, thus I can share
some of my knowledge:
1. Sphinx + GHC HEAD *doesn't work* on Windows if unmodified.
The problem is in 'mkUserGuidePart' utility. It crashes when trying to
create utf8 encoded files when run in the console with default codepage.
But if one changes console codepage to 65001 (chcp 65001) then
'mkUserGuidePart' runs successfully *but* Sphinx stops working
complaining it doesn't know what cp65001 encoding is. I've found that
this fact is known to Python community but they won't fix it in any
Thus, the only way to make *both* mkUserGuidePart and Sphinx work on
windows is to modify mkUserGuidePart.
I've made the following quick fix for it:
diff -urN a/utils/mkUserGuidePart/Main.hs b/utils/mkUserGuidePart/Main.hs
--- a/utils/mkUserGuidePart/Main.hs 2015-10-08 14:09:24.000000000 +0300
+++ b/utils/mkUserGuidePart/Main.hs 2015-10-24 21:42:41.321262400 +0300
@@ -7,6 +7,11 @@
+writeFileUtf8 :: FilePath -> String -> IO ()
+writeFileUtf8 f txt = withFile f WriteMode (\ hdl -> hSetEncoding hdl
utf8 >> hPutStr hdl txt)
-- | A ReStructuredText fragment
type ReST = String
@@ -27,7 +32,7 @@
writeRestFile :: FilePath -> ReST -> IO ()
writeRestFile fname content =
- writeFile fname $ unlines
+ writeFileUtf8 fname $ unlines
[ ".. This file is generated by utils/mkUserGuidePart"
2. Regarding Python installation on Windows -- 2 options worked for me:
-- the simplest is to install WinPython (http://winpython.github.io/)
which contains all necessary bits
-- more problematic is to install mingw-w64-x86_64-python2-sphinx
(change x86_64 for i686 for 32-bit environment) from MSys2. It doesn't
work out of the box and further fixes are necessary:
-- the sphinx driver is called sphinx-build2 instead of sphinx-build
thus one need to modify configure.ac accordingly
-- the sphinx distribution itself is broken because python scripts
are broken, for example, sphinx-build2-script.py starts with
#!/usr/bin/env python2.exe which is wrong because thus it starts MSys2
python (instead of MINGW python) which misses necessary packages. I've
had to modify all related python scripts changing /usr/bin/env
python2.exe to hardcoded MINGW python path.
Hope this helps.
On 26.10.2015 10:59, Simon Peyton Jones wrote:
> The GHC wiki says you need Sphinx to build docs,
> and refers to the Preparation doc for how to install Sphinx
> But the Windows sub-page of Preparation does not say how to install
> Question: how does one install Sphinx on Windows? The sphinx-doc home
> page mutters about ‘pip’, but I’ve never used that. Does anyone have
> ghc-devs mailing list
> ghc-devs at haskell.org
More information about the ghc-devs