Opened 5 years ago

Closed 5 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 Aymeric Augustin 5 years ago.
Makefile.diff (1.2 KB) - added by Aymeric Augustin 5 years ago.
make.bat.diff (829 bytes) - added by Aymeric Augustin 5 years ago.

Download all attachments as: .zip

Change History (14)

comment:1 Changed 5 years ago by Russell Keith-Magee

Resolution: wontfix
Status: newclosed
Type: BugNew 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 5 years ago by alexandrul

Resolution: wontfix
Status: closedreopened

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 5 years ago by 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.

comment:4 Changed 5 years ago by Jannis Leidel

Ah, alexandrul beat me to it.

comment:5 Changed 5 years ago by Aymeric Augustin

Triage Stage: UnreviewedAccepted

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 5 years ago by 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.

Changed 5 years ago by Aymeric Augustin

Attachment: 16414.diff added

Changed 5 years ago by Aymeric Augustin

Attachment: Makefile.diff added

Changed 5 years ago by Aymeric Augustin

Attachment: make.bat.diff added

comment:7 Changed 5 years ago by Aymeric Augustin

Easy pickings: set
Has patch: set

comment:8 Changed 5 years ago by anonymous

Triage Stage: AcceptedReady 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 5 years ago by Aymeric Augustin

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

comment:10 Changed 5 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 5 years ago by Jannis Leidel

Resolution: fixed
Status: reopenedclosed

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