1599142 - Several issues preventing `mach doc` from running on Windows

Status: RESOLVED FIXED

(Developer Infrastructure :: Source Documentation, defect)

Description

[Molly Howell (she/her) (no longer active)]

I've been attempting to add some documentation for a new feature using my Windows development machine, and I've found that the ./mach doc command is not usable on Windows because of several separate issues. I'll list the ones that I've encountered:

1. check_jsdoc attempts to launch a file by the name of jsdoc using subprocess.check_output(). But, the file jsdoc is a Bash script, so it can't be launched this way on Windows. jsdoc.cmd should be used instead.
2. The Sphinx initialization process adds an environment variable called DOCUTILSCONFIG. It always creates this variable as a Unicode string, which in Python 2 means the subprocess module thinks it isn't a string and refuses to use that environment. This results in an exception when trying to set up the virtualenv here.
3. The Windows CopyFile API will fail if the destination directory does not exist. The procedure that creates the staging directory for Sphinx attempts to use this API before any directories are created, so most calls to it fail and most files don't get staged. These errors are ignored, so the result is that Sphinx succeeds in generating a set of documentation that is mostly empty.
4. Several instances where manually constructed paths that contain both back and forward slashes are compared to or otherwise used with normalized paths, resulting in incorrect behaviors.

I have a patch which addresses these and allows me to build the documentation; I'll put it up here.

Comment 1

[Molly Howell (she/her) (no longer active)]

Attachment: Bug 1599142 - Fix several Windows compatibility issues in documentation generation. r=ahal,froydnj

This patch addresses the following issues which prevent building the
documentation on a Windows system:

1. check_jsdoc attempts to launch a file by the name of jsdoc using
   subprocess.check_output(). But, the file jsdoc is a Bash script,
   so it can't be launched this way on Windows. jsdoc.cmd should be
   used instead.
2. The Sphinx initialization process adds an environment variable
   called DOCUTILSCONFIG. It always creates this variable as a Unicode
   string, which in Python 2 means the subprocess module thinks it isn't
   a string and refuses to use that environment. This results in an
   exception when trying to set up the virtualenv here.
3. The Windows CopyFile API will fail if the destination directory does
   not exist. The procedure that creates the staging directory for Sphinx
   attempts to use this API before any directories are created, so most calls
   to it fail and most files don't get staged. These errors are ignored, so
   the result is that Sphinx succeeds in generating a set of documentation
   that is mostly empty.
4. Several instances where manually constructed paths that contain both back
   and forward slashes are compared to or otherwise used with normalized paths,
   resulting in incorrect behaviors.

Comment 2

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/c5a5d332e1b7
Fix several Windows compatibility issues in documentation generation. r=ahal,froydnj

Comment 3

[Narcis Beleuzu [:NarcisB]]

https://hg.mozilla.org/mozilla-central/rev/c5a5d332e1b7