Missing Windows build script for Sphinx

[alexandrul]

Currently the documentation can be built only with the Makefile script. Please add a cmd script for Windows users.

[Russell Keith-Magee]

1. The Windows analog of a Makefile isn't a cmd script. It's a Visual Studio build file. A CMD file is just a batch script, and Makefiles contain significantly more functionality than a simple CMD file would allow.
2. GNU Make is available for Windows. It suffers from the usual problems of unix tools ported to Windows (most notably, a painful installation process), but it is available.

Given that the documentation is available online, is readable in raw source format, and *can* be compiled on Windows given the appropriate tools, I'm going to mark this wontfix. The alternative is for the Django core team to take on the task of developing and/or maintaining a build script for a platform that none of us use regularly, requiring tools that aren't freely available. While we endeavor to support Windows where possible, there is a line at which supporting the eccentricities of Windows exceeds the benefits to the community, and I'm comfortable saying that this change falls on the other side of that line.

[alexandrul]

​http://sphinx.pocoo.org/invocation.html#makefile-options

sphinx-quickstart can generate both the Makefile and the make.bat in a single step. I just hope it's an easy task for the one that generated the Makefile that is currently provided (which is customized a little bit more than usual results of running sphinx-quickstart).

[Jannis Leidel]

FWIW, usually Sphinx generates a make.bat next to the Makefile whose source code you can see here: ​https://bitbucket.org/birkenfeld/sphinx/src/8d38013b4043/sphinx/quickstart.py#cl-516

I could see that shipping that wouldn't be different to us shipping the Makefile.

[Jannis Leidel]

Ah, alexandrul beat me to it.

[Aymeric Augustin]

This was already requested in the comments of #13484. The reported was asked to create a new ticket, but (s)he never did.

[Aymeric Augustin]

I created a new sphinx project, checked the diff between the generated Makefile and Django's Makefile, and applied the same changes to the generated make.bat.

(Un)fortunately, I don't have access to a Windows machine, so I couldn't test the script. I'm attaching the diffs between the default files and Django's version too.

[anonymous]

Using make.bat from the attached 16414.diff with Sphinx 1.0.7:

• make html: build succeeded.
• make epub:

  copying static files... done
  writing mimetype file...
  writing META-INF/container.xml file...
  writing content.opf file...
  WARNING: unknown mimetype for META-INF\container.xml, ignoring
  WARNING: unknown mimetype for _downloads\create_template_postgis-1.3.sh, ignoring
  WARNING: unknown mimetype for _downloads\create_template_postgis-1.4.sh, ignoring
  WARNING: unknown mimetype for _downloads\create_template_postgis-1.5.sh, ignoring
  WARNING: unknown mimetype for _downloads\create_template_postgis-debian.sh, ignoring
  WARNING: unknown mimetype for _downloads\geodjango_setup.bat, ignoring
  WARNING: unknown mimetype for _static\doctools.js, ignoring
  WARNING: unknown mimetype for _static\jquery.js, ignoring
  WARNING: unknown mimetype for _static\searchtools.js, ignoring
  WARNING: unknown mimetype for _static\underscore.js, ignoring
  writing toc.ncx file...
  writing Django.epub file...
  build succeeded, 10 warnings.
  

Regarding the epub warnings, I guess that's another ticket.

[Aymeric Augustin]

The warnings also happen with the Makefile. Indeed, it deserves a separate ticket. I created #16422.

[alexandrul]

What should be done next? The supplied patch works fine here. It must be validated by someone else?

[Jannis Leidel]

In [16547]:

Fixed #16414 -- Added standard Windows make batch file for Sphinx. Thanks, Aymeric Augustin.