Sphinx on Windows

[kyra]

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 at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs