Opened 4 years ago

Closed 4 years ago

#16414 closed New feature (fixed)

Missing Windows build script for Sphinx

Reported by: alexandrul Owned by: nobody
Component: Documentation Version: 1.3
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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

Attachments (3)

16414.diff (4.7 KB) - added by aaugustin 4 years ago.
Makefile.diff (1.2 KB) - added by aaugustin 4 years ago.
make.bat.diff (829 bytes) - added by aaugustin 4 years ago.

Download all attachments as: .zip

Change History (14)

comment:1 Changed 4 years ago by russellm

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to wontfix
  • Status changed from new to closed
  • Type changed from Bug to New feature
  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.

comment:2 Changed 4 years ago by alexandrul

  • Resolution wontfix deleted
  • Status changed from closed to reopened

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).

comment:3 Changed 4 years ago by jezdez

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.

comment:4 Changed 4 years ago by jezdez

Ah, alexandrul beat me to it.

comment:5 Changed 4 years ago by aaugustin

  • Triage Stage changed from Unreviewed to Accepted

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

comment:6 Changed 4 years ago by aaugustin

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.

Changed 4 years ago by aaugustin

Changed 4 years ago by aaugustin

Changed 4 years ago by aaugustin

comment:7 Changed 4 years ago by aaugustin

  • Easy pickings set
  • Has patch set

comment:8 Changed 4 years ago by anonymous

  • Triage Stage changed from Accepted to Ready for checkin

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.

comment:9 Changed 4 years ago by aaugustin

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

comment:10 Changed 4 years ago by alexandrul

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

comment:11 Changed 4 years ago by jezdez

  • Resolution set to fixed
  • Status changed from reopened to closed

In [16547]:

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

Note: See TracTickets for help on using tickets.
Back to Top