[GHC] #11021: Document best practices for bringing up Sphinx on Windows
#11021: Document best practices for bringing up Sphinx on Windows -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Keywords: | Operating System: Unknown/Multiple Architecture: | Type of failure: None/Unknown Unknown/Multiple | Test Case: | Blocked By: Blocking: | Related Tickets: Differential Rev(s): | Wiki Page: -------------------------------------+------------------------------------- The Sphinx documentation tool that we now use to generate the users guide is unfortunately a bit tricky to get working on Windows. See, for instance, https://mail.haskell.org/pipermail/ghc- devs/2015-October/010199.html We need to improve this situation or at very least document how users can build documentation on Windows. -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by awson): * Attachment "mkUserGuidePart_fix_writeFile.patch" added. -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by awson): To clarify what is written in the cited (my) e-mail: the problem with Windows console codepage 65001 is not Sphinx-specific but pervades the whole Python ecosystem. And Python people won't fix it. Thus the only way to happily build GHC documentation with Sphinx on Windows is to modify `mkUserGuidePart`. I've attached the cited patch as a separate file for convenience. Patch is very simple and basically tells handle I/O functions to expect `utf8`-encoded content. I didn't guard the changes to be Windows-specific because I think it is at least harmless on other systems and, perhaps, can help in some other peculiar configurations. Regarding Sphinx installation I believe the most "automated" way would be to add MSys2/MINGW Sphinx package as another MSys2/MINGW dependency, but this requires not only `configure.ac` modification but (most important) fixing MSys2/MINGW Sphinx package itself, which should better be upstreamed to MSys2/MINGW, and I have no time to do this ATM, sorry. -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:1> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows ----------------------------------+---------------------------------------- Reporter: bgamari | Owner: Type: task | Status: patch Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Windows | Architecture: Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | ----------------------------------+---------------------------------------- Changes (by thomie): * status: new => patch * os: Unknown/Multiple => Windows -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:2> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows ----------------------------------+---------------------------------------- Reporter: bgamari | Owner: Phyx- Type: task | Status: patch Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Windows | Architecture: Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | ----------------------------------+---------------------------------------- Changes (by Phyx-): * owner: => Phyx- -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:3> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows ----------------------------------+---------------------------------------- Reporter: bgamari | Owner: Phyx- Type: task | Status: patch Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Windows | Architecture: Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D1408 Wiki Page: | ----------------------------------+---------------------------------------- Changes (by Phyx-): * differential: => Phab:D1408 Comment: Thanks @awson -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:4> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows ----------------------------------+---------------------------------------- Reporter: bgamari | Owner: Phyx- Type: task | Status: patch Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Windows | Architecture: Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D1408 Wiki Page: | ----------------------------------+---------------------------------------- Comment (by Tamar Christina <tamar@…>): In [changeset:"6bef55c6b561080c5ddff73f2c501e40acee86ef/ghc" 6bef55c6/ghc]: {{{ #!CommitTicketReference repository="ghc" revision="6bef55c6b561080c5ddff73f2c501e40acee86ef" Fix documentation build on windows Summary: Fix building new Sphinx documenation on Windows in msys2 using Awson's patch on #11021. Install Sphinx using `pacman -S mingw-w64-$(uname -m)-python2-sphinx` Test Plan: Apply patch and ./validate Reviewers: thomie, bgamari, austin Reviewed By: thomie, bgamari Subscribers: erikd Differential Revision: https://phabricator.haskell.org/D1408 GHC Trac Issues: #11021 }}} -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:5> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows ----------------------------------+---------------------------------------- Reporter: bgamari | Owner: Phyx- Type: task | Status: closed Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: fixed | Keywords: Operating System: Windows | Architecture: Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D1408 Wiki Page: | ----------------------------------+---------------------------------------- Changes (by Phyx-): * status: patch => closed * resolution: => fixed -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:6> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows ----------------------------------+---------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Windows | Architecture: Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D1408 Wiki Page: | ----------------------------------+---------------------------------------- Changes (by Phyx-): * owner: Phyx- => * status: closed => new * resolution: fixed => Comment: Just ran into the codepage issue @awson mentioned. Worked the first validate but subsequent ones failed.. don't know why. In any case, the issue seems to be fixed in `python3` https://docs.python.org/dev/whatsnew/3.3.html#codecs and https://bugs.python.org/issue13216 Sphinx also has support for `python 3.3+` so I will make a patch to use the `python3` version of Sphinx and revalidate. -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:7> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: patch Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Windows | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D1408 Wiki Page: | Phab:D1417 -------------------------------------+------------------------------------- Changes (by Phyx-): * status: new => patch * differential: Phab:D1408 => Phab:D1408 Phab:D1417 -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:8> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Phyx- Type: task | Status: patch Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Windows | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D1408 Wiki Page: | Phab:D1417 -------------------------------------+------------------------------------- Changes (by Phyx-): * owner: => Phyx- -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:9> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Phyx- Type: task | Status: patch Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: | Keywords: Operating System: Windows | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D1408 Wiki Page: | Phab:D1417 -------------------------------------+------------------------------------- Comment (by Tamar Christina <tamar@…>): In [changeset:"65f3c4c0a1304b8d00b46dc0e77ad93fc566ffb1/ghc" 65f3c4c0/ghc]: {{{ #!CommitTicketReference repository="ghc" revision="65f3c4c0a1304b8d00b46dc0e77ad93fc566ffb1" Change sphinx for documentation building on windows to the python3 version Summary: Python 3 seems to have fixed the long standing codepage issue with python on Windows. To be able to reliably build the documentation we should use the Python 3 version of Sphinx. See `https://docs.python.org/dev/whatsnew/3.3.html#codecs` and `https://bugs.python.org/issue13216`. Sphinx also supports Python 3. Oddly enough `python3-sphinx` is registered as `sphinx-build.exe` instead of `sphinx-build3.exe`, so the changes in `configure.ac` can be reverted. install with `pacman -S mingw-w64-$(uname -m)-python3-sphinx` Test Plan: ./validate Reviewers: austin, thomie, bgamari Reviewed By: bgamari Subscribers: erikd Differential Revision: https://phabricator.haskell.org/D1417 GHC Trac Issues: #11021 }}} -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:10> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11021: Document best practices for bringing up Sphinx on Windows -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Phyx- Type: task | Status: closed Priority: normal | Milestone: 8.0.1 Component: Documentation | Version: 7.11 Resolution: fixed | Keywords: Operating System: Windows | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D1408 Wiki Page: | Phab:D1417 -------------------------------------+------------------------------------- Changes (by Phyx-): * status: patch => closed * resolution: => fixed Comment: Should now be really fixed. -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11021#comment:11> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
participants (1)
-
GHC