[GHC] #11021: Document best practices for bringing up Sphinx on Windows

[GHC]

#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