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 foreseeable future. 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 @@ import Table import Options +import System.IO + +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" , "" , content 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. Cheers, Kyra On 26.10.2015 10:59, Simon Peyton Jones wrote:
The GHC wiki says you need Sphinx to build docs,
https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Tools
and refers to the Preparation doc for how to install Sphinx
https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation
But the Windows sub-page of Preparation does not say how to install Sphinx.
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 instructions?
Thanks
Simon
_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs