Sphinx on Windows

[Simon Peyton Jones]

Thanks.  I'll just disable it for now.

When you have this sorted out, could you add something to the Windows instructions for GHC devs?  That'd be super-helpful

Simon

|  -----Original Message-----
|  From: ghc-devs [mailto:ghc-devs-bounces at haskell.org] On Behalf Of kyra
|  Sent: 26 October 2015 14:40
|  To: ghc-devs at haskell.org
|  Subject: Re: Sphinx on Windows
|  
|  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
|  (https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2fwinpython.g
|  ithub.io%2f&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c8b1e7e1d25f548
|  6c3b2e08d2de136222%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=hreGbIXD5Fcq
|  HRYefVgz54Yr9UwsFjfXMui1MLZ97UI%3d)
|  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
|  https://na01.safelinks.protection.outlook.com/?url=configure.ac&data=01%7c01
|  %7csimonpj%40064d.mgd.microsoft.com%7c8b1e7e1d25f5486c3b2e08d2de136222%7c72f
|  988bf86f141af91ab2d7cd011db47%7c1&sdata=LkUUK8z66o9oJH3zM%2fVdZvwhEeOwaVzqYE
|  %2fue8NMrNU%3d accordingly
|      -- the sphinx distribution itself is broken because python scripts are
|  broken, for example,
|  https://na01.safelinks.protection.outlook.com/?url=sphinx-build2-
|  script.py&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c8b1e7e1d25f5486c
|  3b2e08d2de136222%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=bwwa7fhpWKWWXE
|  QIHyopPVoPd0DiVb9p5HvkvoUVNis%3d 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
|  > https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2fmail.h
|  > askell.org%2fcgi-bin%2fmailman%2flistinfo%2fghc-devs&data=01%7c01%7csi
|  > monpj%40064d.mgd.microsoft.com%7c8b1e7e1d25f5486c3b2e08d2de136222%7c72
|  > f988bf86f141af91ab2d7cd011db47%7c1&sdata=8teFBXUzJgll4Eo0pBReMMOMd6v%2
|  > bdQQ1yhOp3u9M3og%3d
|  
|  _______________________________________________
|  ghc-devs mailing list
|  ghc-devs at haskell.org
|  https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2fmail.haskell
|  .org%2fcgi-bin%2fmailman%2flistinfo%2fghc-
|  devs&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c8b1e7e1d25f5486c3b2e0
|  8d2de136222%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=8teFBXUzJgll4Eo0pBR
|  eMMOMd6v%2bdQQ1yhOp3u9M3og%3d