Sphinx on Windows

Simon Peyton Jones

26 Oct 2015 26 Oct '15

7:59 a.m.

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

Attachments:

attachment.html (text/html — 3.4 KB)

Show replies by date

Herbert Valerio Riedel

26 Oct 26 Oct

8:27 a.m.

Hi, On 2015-10-26 at 08:59:26 +0100, 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?

Have you tried following the instructions on http://sphinx-doc.org/latest/install.html#windows-install-python-and-sphinx ? If those instructions work, I guess we should link there... Cheers, hvr

David Kraeutmann

8:32 a.m.

'pip' is just a Python package manager. Following the steps at http://sphinx-doc.org/latest/install.html#windows-install-python-and-sphinx should give you a working sphinx install. I can test those on my Windows machine once I'm home, but that won't be for a few hours. On Mon, Oct 26, 2015 at 8:59 AM, 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

Simon Peyton Jones

9:41 a.m.

I have not tried that. But 'pip' gives "command not found". Maybe I need something in my path? I appear to have python 2.7.5 installed; it does not appear to have pip.exe. Simon | -----Original Message----- | From: David Kraeutmann [mailto:kane@kane.cx] | Sent: 26 October 2015 08:32 | To: Simon Peyton Jones | Cc: ghc-devs@haskell.org | Subject: Re: Sphinx on Windows | | 'pip' is just a Python package manager. Following the steps at | https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2fsphinx- | doc.org%2flatest%2finstall.html%23windows-install-python-and- | sphinx&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c865e98e064ee4e54daa | d08d2dddff6dd%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=TtHa5dAl%2fEASoNW | kXJDQ0Om6ilkxRguR%2bpBrZP19ujc%3d | should give you a working sphinx install. I can test those on my Windows | machine once I'm home, but that won't be for a few hours. | | On Mon, Oct 26, 2015 at 8:59 AM, 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 | > https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2fmail.h | > askell.org%2fcgi-bin%2fmailman%2flistinfo%2fghc- | devs&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c865e98e064ee4e54daad0 | 8d2dddff6dd%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=zUsjfvEKGbIjR%2b9QP | InIXPKB7P%2bt2zXcPxLPvHlzWNs%3d | >

David Kraeutmann

10:01 a.m.

Grab https://bootstrap.pypa.io/get-pip.py and do `python get-pip.py' from a command prompt (might need to be elevated, not sure). After that 'pip' should be available and you can do 'pip install sphinx'. On Mon, Oct 26, 2015 at 10:41 AM, Simon Peyton Jones wrote:

...

I have not tried that. But 'pip' gives "command not found".

Maybe I need something in my path? I appear to have python 2.7.5 installed; it does not appear to have pip.exe.

Simon

| -----Original Message----- | From: David Kraeutmann [mailto:kane@kane.cx] | Sent: 26 October 2015 08:32 | To: Simon Peyton Jones | Cc: ghc-devs@haskell.org | Subject: Re: Sphinx on Windows | | 'pip' is just a Python package manager. Following the steps at | https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2fsphinx- | doc.org%2flatest%2finstall.html%23windows-install-python-and- | sphinx&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c865e98e064ee4e54daa | d08d2dddff6dd%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=TtHa5dAl%2fEASoNW | kXJDQ0Om6ilkxRguR%2bpBrZP19ujc%3d | should give you a working sphinx install. I can test those on my Windows | machine once I'm home, but that won't be for a few hours. | | On Mon, Oct 26, 2015 at 8:59 AM, 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 | > https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2fmail.h | > askell.org%2fcgi-bin%2fmailman%2flistinfo%2fghc- | devs&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c865e98e064ee4e54daad0 | 8d2dddff6dd%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=zUsjfvEKGbIjR%2b9QP | InIXPKB7P%2bt2zXcPxLPvHlzWNs%3d | >

Simon Peyton Jones

10:07 a.m.

Thanks. But it's a bit inefficient to debug by email. For now I've simply switched off the sphinx stuff in my build.mk. Might you work it through when you have access to a machine, and document the result? If the desired sequence is to * get pip * use pip to get sphinx then could the docs on https://ghc.haskell.org/trac/ghc/wiki/Building/Preparation/Windows be update to say precisely that? Someone went to some trouble to make that page short and easy, and perhaps there is a more direct route. I'm not sure. Many thanks Simon | -----Original Message----- | From: David Kraeutmann [mailto:kane@kane.cx] | Sent: 26 October 2015 10:01 | To: Simon Peyton Jones | Cc: ghc-devs@haskell.org | Subject: Re: Sphinx on Windows | | Grab | https://na01.safelinks.protection.outlook.com/?url=https%3a%2f%2fbootstrap.p | ypa.io%2fget- | pip.py&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c2143737483a740eb651 | 308d2ddec5e3d%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=YnlD5KrF3LBjq2ys8 | M4ZSsv26Qgrwo7WdYYaUh2sNiU%3d and do `python | https://na01.safelinks.protection.outlook.com/?url=get- | pip.py&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c2143737483a740eb651 | 308d2ddec5e3d%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=2DVk4wuIWO9bYpS7Y | XBuInrDI9jER9ETucrMnvvPjEA%3d' | from a command prompt (might need to be elevated, not sure). After that | 'pip' should be available and you can do 'pip install sphinx'. | | On Mon, Oct 26, 2015 at 10:41 AM, Simon Peyton Jones | wrote: | > I have not tried that. But 'pip' gives "command not found". | > | > Maybe I need something in my path? I appear to have python 2.7.5 | installed; it does not appear to have pip.exe. | > | > Simon | > | > | -----Original Message----- | > | From: David Kraeutmann [mailto:kane@kane.cx] | > | Sent: 26 October 2015 08:32 | > | To: Simon Peyton Jones | > | Cc: ghc-devs@haskell.org | > | Subject: Re: Sphinx on Windows | > | | > | 'pip' is just a Python package manager. Following the steps at | > | | > | https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2fsphi | > | nx- | > | doc.org%2flatest%2finstall.html%23windows-install-python-and- | > | | > | sphinx&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c865e98e064e | > | e4e54daa | > | d08d2dddff6dd%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=TtHa5dAl% | > | 2fEASoNW | > | kXJDQ0Om6ilkxRguR%2bpBrZP19ujc%3d | > | should give you a working sphinx install. I can test those on my | > | Windows machine once I'm home, but that won't be for a few hours. | > | | > | On Mon, Oct 26, 2015 at 8:59 AM, 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 | > | > | > | https://na01.safelinks.protection.outlook.com/?url=http%3a%2f%2fmail | > | .h > askell.org%2fcgi-bin%2fmailman%2flistinfo%2fghc- | > | | > | devs&data=01%7c01%7csimonpj%40064d.mgd.microsoft.com%7c865e98e064ee4 | > | e54daad0 | > | 8d2dddff6dd%7c72f988bf86f141af91ab2d7cd011db47%7c1&sdata=zUsjfvEKGbI | > | jR%2b9QP | > | InIXPKB7P%2bt2zXcPxLPvHlzWNs%3d | > | >

Ben Gamari

10:38 a.m.

Simon Peyton Jones writes:

...

I have not tried that. But 'pip' gives "command not found".

Maybe I need something in my path? I appear to have python 2.7.5 installed; it does not appear to have pip.exe.

Pip ships with Python 2.7.9 and later. Alternatively, you this script [1] will install pip for you. Just download it and run it with, $ python get-pip.py See the Sphinx installation page [2] for details. Cheers, - Ben [1] https://bootstrap.pypa.io/get-pip.py [2] http://sphinx-doc.org/install.html#windows-install-python-and-sphinx

kyra

2:40 p.m.

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

Simon Peyton Jones

3:20 p.m.

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@haskell.org] On Behalf Of kyra | Sent: 26 October 2015 14:40 | To: ghc-devs@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@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@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

Ben Gamari

4 p.m.

kyra writes:

...

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:

Thanks for writing this down, Kyra! These notes are very helpful. Would you like to add a comment to your patch describing the rationale for the change and open a Phabricator Differential [1] so we can get it upstream? Cheers, - Ben [1] https://ghc.haskell.org/trac/ghc/wiki/Phabricator

3542

Age (days ago)

3542

Last active (days ago)

List overview

Download

9 comments

6 participants

participants (6)

Ben Gamari
Ben Gamari
David Kraeutmann
Herbert Valerio Riedel
kyra
Simon Peyton Jones

Sphinx on Windows

tags

participants (6)