CI : Enable Sphinx docs builds on Windows

A few of the `sphinxcontrib-` package versions installed here are slightly older than those we use in the Linux build containers. This is required because the Windows build environment is Python 3.7 and the newer packages have dropped support for that version. This doesn't appear to make a difference in practice.

.github/workflows/main.yml

@@ -109,6 +109,7 @@ jobs:
     - name: Install toolchain (Windows)
       run: |
         python -m pip install scons
+        python -m pip install sphinx==4.3.1 sphinx_rtd_theme==1.0.0 myst-parser==0.15.2 docutils==0.17.1 sphinxcontrib-applehelp==1.0.2 sphinxcontrib-devhelp==1.0.2 sphinxcontrib-htmlhelp==2.0.0 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-serializinghtml==1.1.5 sphinxcontrib-qthelp==1.0.3
         Invoke-WebRequest -Uri "https://inkscape.org/gallery/item/37363/inkscape-1.2.2_2022-12-09_732a01da63-x64.exe" -OutFile "inkscape.exe"
         Start-Process .\inkscape.exe /S -NoNewWindow -Wait
       shell: pwsh

.github/workflows/main/sconsOptions

@@ -61,5 +61,5 @@ if sys.platform == "win32" :
 	LOCATE_DEPENDENCY_PYTHONPATH=os.path.join(os.environ["GAFFER_BUILD_DIR"], "python")
 	GLEW_LIB_SUFFIX = "32"
 	INKSCAPE = "C:\\Program Files\\Inkscape\\bin\\inkscape.exe"
-	SPHINX = "noSphinxYet"
+	SPHINX = "sphinx-build.exe"
 	ENV_VARS_TO_IMPORT += " GALLIUM_DRIVER"

.github/workflows/main/setBuildVars.py

@@ -172,15 +172,6 @@
 	print( "Setting $GAFFER_GITHUB_RELEASEID to '%s'" % releaseId )
 	f.write( 'GAFFER_GITHUB_RELEASEID=%s\n' % releaseId )
 
-	if os.name == "nt" :
-		packageExtension = "zip"
-
-		# \todo Remove this when docs are ready to build
-		print( "Setting $GAFFER_VALIDATE_EXTRA_FLAGS to '--skipDocs'" )
-		f.write( 'GAFFER_VALIDATE_EXTRA_FLAGS=--skipDocs\n' )
-
-	else :
-		packageExtension = "tar.gz"
-
+	packageExtension = "zip" if os.name == "nt" else "tar.gz"
 	print( "Setting $PACKAGE_EXTENSION to '%s'" %packageExtension )
 	f.write( 'PACKAGE_EXTENSION=%s\n' %packageExtension )

Changes.md

@@ -11,6 +11,11 @@ Fixes
 
 - WidgetAlgo : Fixed issue preventing `grab()` from capturing popup menus on Windows.
 
+Documentation
+-------------
+
+- Windows : Documentation is now included in Windows release packages.
+
 1.4.10.0 (relative to 1.4.9.0)
 ========
 

SConstruct

@@ -2182,13 +2182,17 @@ def generateDocs( target, source, env ) :
 	localFile = os.path.basename( str(source[0]) )
 
 	ext = os.path.splitext( localFile )[1]
+	gafferCmd = shutil.which( "gaffer.cmd" if sys.platform == "win32" else "gaffer", path = env["ENV"]["PATH"] )
 	command = []
 	if localFile == "screengrab.py" :
-		command = [ "gaffer", "screengrab", "-commandFile", localFile ]
+		command = [ gafferCmd, "screengrab", "-commandFile", localFile ]
 	elif ext == ".py" :
-		command = [ "gaffer", "env", "python", localFile ]
+		command = [ gafferCmd, "env", "python", localFile ]
 	elif ext == ".sh" :
-		command = [ "gaffer", "env", "./" + localFile ]
+		if sys.platform == "win32" :
+			command = [ gafferCmd, "env", "sh", "./" + localFile ]
+		else :
+			command = [ gafferCmd, "env", "./" + localFile ]
 	if command :
 		sys.stdout.write( "Running {0}\n".format( os.path.join( root, localFile ) ) )
 		subprocess.check_call( command, cwd = root, env = env["ENV"] )
@@ -2257,7 +2261,7 @@ if haveSphinx and haveInkscape :
 	# use host python to avoid needing a matrix of sphinx versions to match Gaffer's
 	# bundled python version.
 	docEnv = env.Clone()
-	docEnv["ENV"]["PYTHONPATH"] = ":".join( sys.path )
+	docEnv["ENV"]["PYTHONPATH"] = os.path.pathsep.join( sys.path )
 
 	# Since we don't copy the docs reference scripts, the screengrab
 	# scripts must read them from the source, so we use the reference
@@ -2273,9 +2277,9 @@ if haveSphinx and haveInkscape :
 	libraryPathEnvVar = "DYLD_LIBRARY_PATH" if docEnv["PLATFORM"]=="darwin" else "LD_LIBRARY_PATH"
 
 	if docCommandEnv.subst( "$ARNOLD_ROOT" ) :
-		docCommandEnv["ENV"]["PATH"] += ":" + docCommandEnv.subst( "$ARNOLD_ROOT/bin" )
-		docCommandEnv["ENV"]["PYTHONPATH"] += ":" + docCommandEnv.subst( "$ARNOLD_ROOT/python" )
-		docCommandEnv["ENV"][libraryPathEnvVar] = docCommandEnv["ENV"].get( libraryPathEnvVar, "" ) + ":" + docCommandEnv.subst( "$ARNOLD_ROOT/bin" )
+		docCommandEnv["ENV"]["PATH"] += os.path.pathsep + docCommandEnv.subst( "$ARNOLD_ROOT/bin" )
+		docCommandEnv["ENV"]["PYTHONPATH"] += os.path.pathsep + docCommandEnv.subst( "$ARNOLD_ROOT/python" )
+		docCommandEnv["ENV"][libraryPathEnvVar] = docCommandEnv["ENV"].get( libraryPathEnvVar, "" ) + os.path.pathsep + docCommandEnv.subst( "$ARNOLD_ROOT/bin" )
 
 	#  Docs graphics generation
 	docGraphicsCommands = graphicsCommands( docEnv, "resources/docGraphics.svg", "$BUILD_DIR/doc/gaffer/graphics" )