Merge pull request #5978 from GafferHQ/windowsDocs

Windows Documentation Build

.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
@@ -165,6 +166,8 @@ jobs:
         curl.exe -L --output mesa.7z --url https://github.com/pal1000/mesa-dist-win/releases/download/22.3.1/mesa3d-22.3.1-release-msvc.7z
         & "C:\Program Files\7-Zip\7z.exe" x mesa.7z -omesa
         ./mesa/systemwidedeploy.cmd 1
+        echo "GALLIUM_DRIVER=llvmpipe" >> $env:GITHUB_ENV
+        Set-DisplayResolution -Width 1280 -Height 1024 -Force
       shell: pwsh
       if: runner.os == 'Windows'
 

.github/workflows/main/sconsOptions

@@ -61,4 +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

@@ -10,6 +10,13 @@ Fixes
 -----
 
 - Arnold : Fixed bug preventing UI metadata for Imagers from being loaded for Arnold 7.3.
+- WidgetAlgo : Fixed issue preventing `grab()` from capturing popup menus on Windows.
+- ShowURL : Fixed opening of "file://" URLs on Windows (#5861).
+
+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" )

doc/source/Reference/CommandLineReference/generate.py

@@ -1,6 +1,7 @@
 # BuildTarget: index.md
 # UndeclaredBuildTargets
 
+import Gaffer
 import GafferUI
 
 GafferUI.DocumentationAlgo.exportCommandLineReference( "./", ignore = { "op" } )

doc/source/Reference/NodeReference/generate.py

@@ -1,6 +1,7 @@
 # BuildTarget: index.md
 # UndeclaredBuildTargets
 
+import Gaffer
 import GafferUI
 
 # GafferArnold isn't installed under the standard module path

doc/source/WorkingWithScenes/AnatomyOfACamera/screengrab.py

@@ -50,5 +50,6 @@
 
 	window.resizeToFitChild()
 	window.setVisible( True )
+	window.setPosition( imath.V2i( 0, 0 ) )
 
 	GafferUI.WidgetAlgo.grab( widget = sceneInspector, imagePath = "images/interfaceCamera" + imageName )

doc/source/WorkingWithScenes/AnatomyOfAScene/screengrab.py

@@ -83,5 +83,6 @@ def __delay( delay ) :
 
 	window.resizeToFitChild()
 	window.setVisible( True )
+	__delay( 0.5 )
 
 	GafferUI.WidgetAlgo.grab( widget = sceneInspector, imagePath = "images/sceneInspector" + imageName )

doc/source/WorkingWithScenes/Camera/screengrab.py

@@ -16,6 +16,7 @@
 # BuildDependency: scripts/taskStandardOptionsDepthOfFieldPlug_edit.gfr
 
 import os
+import pathlib
 import subprocess
 import tempfile
 import time
@@ -39,20 +40,23 @@ def __delay( delay ) :
 		GafferUI.EventLoop.waitForIdle( 1 )
 
 # Create a random directory in `/tmp` for the dispatcher's `jobsDirectory`, so we don't clutter the user's `~gaffer` directory
-__temporaryDirectory = tempfile.mkdtemp( prefix = "gafferDocs" )
+__temporaryDirectory = pathlib.Path( tempfile.mkdtemp( prefix = "gafferDocs" ) )
 
 def __getTempFilePath( fileName, directory = __temporaryDirectory ) :
-	filePath = "/".join( ( directory, fileName ) )
 
-	return filePath
+	return ( directory / fileName ).as_posix()
+
+def __outputImagePath( fileName ) :
+
+	return pathlib.Path( "images/{}.png".format( fileName ) ).absolute().as_posix()
 
 def __dispatchScript( script, tasks, settings ) :
 	command = "gaffer dispatch -script {} -tasks {} -dispatcher Local -settings {} -dispatcher.jobsDirectory '\"{}/dispatcher/local\"'".format(
 		script,
 		" ".join( tasks ),
 		" ".join( settings ),
-		__temporaryDirectory
-		)
+		__temporaryDirectory.as_posix()
+	)
 	subprocess.check_call( command, shell=True )
 
 # Interface: a Camera node in the Graph Editor
@@ -127,9 +131,9 @@ def __dispatchScript( script, tasks, settings ) :
 	tasks = [ "ImageWriter" ],
 	settings = [
 		"-ImageReader.fileName '\"{}\"'".format( __tempImagePath ),
-		"-ImageWriter.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-	)
+		"-ImageWriter.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: the Aperture and Focal Length projection mode in the Node Editor
 __imageName = "taskCameraApertureFocalLengthPlugs"
@@ -143,9 +147,9 @@ def __dispatchScript( script, tasks, settings ) :
 	tasks = [ "ImageWriter" ],
 	settings = [
 		"-ImageReader.fileName '\"{}\"'".format( __tempImagePath ),
-		"-ImageWriter.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-	)
+		"-ImageWriter.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: the Custom aperture mode and aperture.x and aperture.y plugs in the Node Editor
 __imageName = "taskCameraCustomAperturePlugs"
@@ -158,9 +162,9 @@ def __dispatchScript( script, tasks, settings ) :
 	tasks = [ "ImageWriter" ],
 	settings = [
 		"-ImageReader.fileName '\"{}\"'".format( __tempImagePath),
-		"-ImageWriter.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-  )
+		"-ImageWriter.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: animation of adjusting the Aperture Offset in the Node Editor, and the corresponding changes to the camera's frustrum in the Viewer
 ## TODO: Automate `images/taskApertureOffset.gif` when these tools become available:
@@ -173,9 +177,9 @@ def __dispatchScript( script, tasks, settings ) :
 	script = "scripts/{}.gfr".format( __imageName ),
 	tasks = [ "Render" ],
 	settings = [
-		"-Outputs.outputs.output1.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-  )
+		"-Outputs.outputs.output1.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: the Depth of Field tab, with settings, in the Node Editor
 script["Camera"]["focusDistance"].setValue( 22.0 )
@@ -202,9 +206,9 @@ def __dispatchScript( script, tasks, settings ) :
 	tasks = [ "ImageWriter" ],
 	settings = [
 		"-ImageReader.fileName '\"{}\"'".format( __tempImagePath ),
-		"-ImageWriter.fileName '\"{}\"'".format( os.path.abspath( "images/{}.png".format( __imageName ) ) )
-		]
-	)
+		"-ImageWriter.fileName '\"{}\"'".format( __outputImagePath( __imageName ) )
+	]
+)
 
 # Task: a Camera node's Render Overrides tab in the Node Editor
 script["Camera"]["renderSettingOverrides"]["resolution"]["value"].setValue( imath.V2i( 5120, 2160 ) )
@@ -236,15 +240,15 @@ def __dispatchScript( script, tasks, settings ) :
 
 # Example: Anamorphic Camera Setup
 __dispatchScript(
-	script = os.path.abspath( "../../../examples/rendering/anamorphicCameraSetup.gfr" ),
+	script = pathlib.Path( "../../../examples/rendering/anamorphicCameraSetup.gfr" ).absolute().as_posix(),
 	tasks = [ "Render" ],
 	settings = [
-		"-StandardOptions.options.renderResolution.value.x '240'",
-		"-StandardOptions.options.renderResolution.value.y '270'",
-		"-Outputs.outputs.output1.fileName '\"{}\"'".format( os.path.abspath( "images/exampleAnamorphicCameraSetup.png" ) ),
+		"-StandardOptions.options.renderResolution.value.x 240",
+		"-StandardOptions.options.renderResolution.value.y 270",
+		"-Outputs.outputs.output1.fileName '\"{}\"'".format( __outputImagePath( "exampleAnamorphicCameraSetup" ) ),
 		"-Outputs.outputs.output1.type '\"png\"'"
-		]
-	)
+	]
+)
 
 # Example: Spherical Camera Setup in Arnold
 # __dispatchScript(

doc/source/WorkingWithScenes/Camera/scripts/taskCameraApertureFocalLengthPlugs_edit.gfr

@@ -1,25 +1,19 @@
 import Gaffer
 import GafferDispatch
 import GafferImage
-import IECore
+import GafferOSL
 import imath
 
-Gaffer.Metadata.registerValue( parent, "serialiser:milestoneVersion", 0, persistent=False )
-Gaffer.Metadata.registerValue( parent, "serialiser:majorVersion", 53, persistent=False )
-Gaffer.Metadata.registerValue( parent, "serialiser:minorVersion", 1, persistent=False )
+Gaffer.Metadata.registerValue( parent, "serialiser:milestoneVersion", 1, persistent=False )
+Gaffer.Metadata.registerValue( parent, "serialiser:majorVersion", 4, persistent=False )
+Gaffer.Metadata.registerValue( parent, "serialiser:minorVersion", 6, persistent=False )
 Gaffer.Metadata.registerValue( parent, "serialiser:patchVersion", 0, persistent=False )
 
 __children = {}
 
-parent["variables"].addChild( Gaffer.CompoundDataPlug.MemberPlug( "imageCataloguePort", flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
-parent["variables"]["imageCataloguePort"].addChild( Gaffer.StringPlug( "name", defaultValue = 'image:catalogue:port', flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
-parent["variables"]["imageCataloguePort"].addChild( Gaffer.IntPlug( "value", defaultValue = 0, flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
-parent["variables"].addChild( Gaffer.CompoundDataPlug.MemberPlug( "projectName", flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
-parent["variables"]["projectName"].addChild( Gaffer.StringPlug( "name", defaultValue = 'project:name', flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
-parent["variables"]["projectName"].addChild( Gaffer.StringPlug( "value", defaultValue = 'default', flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
-parent["variables"].addChild( Gaffer.CompoundDataPlug.MemberPlug( "projectRootDirectory", flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
-parent["variables"]["projectRootDirectory"].addChild( Gaffer.StringPlug( "name", defaultValue = 'project:rootDirectory', flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
-parent["variables"]["projectRootDirectory"].addChild( Gaffer.StringPlug( "value", defaultValue = '$HOME/gaffer/projects/${project:name}', flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
+parent["variables"].addChild( Gaffer.NameValuePlug( "image:catalogue:port", Gaffer.IntPlug( "value", defaultValue = 0, flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ), "imageCataloguePort", Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic ) )
+parent["variables"].addChild( Gaffer.NameValuePlug( "project:name", Gaffer.StringPlug( "value", defaultValue = 'default', flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ), "projectName", Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic ) )
+parent["variables"].addChild( Gaffer.NameValuePlug( "project:rootDirectory", Gaffer.StringPlug( "value", defaultValue = '$HOME/gaffer/projects/${project:name}', flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ), "projectRootDirectory", Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic ) )
 __children["defaultFormat"] = GafferImage.FormatPlug( "defaultFormat", defaultValue = GafferImage.Format( 1920, 1080, 1.000 ), flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, )
 parent.addChild( __children["defaultFormat"] )
 __children["ImageReader"] = GafferImage.ImageReader( "ImageReader" )
@@ -31,16 +25,27 @@ __children["Rectangle"].addChild( Gaffer.V2fPlug( "__uiPosition", defaultValue =
 __children["ImageWriter"] = GafferImage.ImageWriter( "ImageWriter" )
 parent.addChild( __children["ImageWriter"] )
 __children["ImageWriter"].addChild( Gaffer.V2fPlug( "__uiPosition", defaultValue = imath.V2f( 0, 0 ), flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
-parent["variables"]["imageCataloguePort"]["value"].setValue( 39199 )
+__children["openColorIO"] = GafferImage.OpenColorIOConfigPlug( "openColorIO", flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, )
+parent.addChild( __children["openColorIO"] )
+__children["FormatQuery"] = GafferImage.FormatQuery( "FormatQuery" )
+parent.addChild( __children["FormatQuery"] )
+__children["FormatQuery"].addChild( Gaffer.V2fPlug( "__uiPosition", defaultValue = imath.V2f( 0, 0 ), flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
+__children["Expression"] = Gaffer.Expression( "Expression" )
+parent.addChild( __children["Expression"] )
+__children["Expression"]["__in"].addChild( Gaffer.IntPlug( "p0", defaultValue = 0, flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
+__children["Expression"]["__out"].addChild( Gaffer.FloatPlug( "p0", direction = Gaffer.Plug.Direction.Out, defaultValue = 100.0, flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
+__children["Expression"].addChild( Gaffer.V2fPlug( "__uiPosition", defaultValue = imath.V2f( 0, 0 ), flags = Gaffer.Plug.Flags.Default | Gaffer.Plug.Flags.Dynamic, ) )
+parent["variables"]["imageCataloguePort"]["value"].setValue( 62365 )
 Gaffer.Metadata.registerValue( parent["variables"]["imageCataloguePort"], 'readOnly', True )
 Gaffer.Metadata.registerValue( parent["variables"]["projectName"]["name"], 'readOnly', True )
 Gaffer.Metadata.registerValue( parent["variables"]["projectRootDirectory"]["name"], 'readOnly', True )
 __children["ImageReader"]["colorSpace"].setValue( 'raw' )
 __children["ImageReader"]["__uiPosition"].setValue( imath.V2f( -22.6491661, 10.4499998 ) )
-__children["Rectangle"]["out"].setInput( __children["Rectangle"]["__merge"]["out"] )
 __children["Rectangle"]["in"].setInput( __children["ImageReader"]["out"] )
 __children["Rectangle"]["color"].setValue( imath.Color4f( 0.964699984, 0.57249999, 0.113700002, 1 ) )
-__children["Rectangle"]["area"].setValue( imath.Box2f( imath.V2f( 8, 165 ), imath.V2f( 446, 242 ) ) )
+__children["Rectangle"]["area"]["min"].setValue( imath.V2f( 8, 165 ) )
+__children["Rectangle"]["area"]["max"]["y"].setValue( 242.0 )
+__children["Rectangle"]["area"]["max"]["x"].setInput( __children["Expression"]["__out"]["p0"] )
 __children["Rectangle"]["cornerRadius"].setValue( 4.0 )
 __children["Rectangle"]["__uiPosition"].setValue( imath.V2f( -22.6491661, 2.28593731 ) )
 __children["ImageWriter"]["in"].setInput( __children["Rectangle"]["out"] )
@@ -49,6 +54,12 @@ Gaffer.Metadata.registerValue( __children["ImageWriter"]["channels"], 'channelMa
 __children["ImageWriter"]["colorSpace"].setValue( 'raw' )
 __children["ImageWriter"]["png"]["compressionLevel"].setValue( 9 )
 __children["ImageWriter"]["__uiPosition"].setValue( imath.V2f( -24.1491661, -5.87812519 ) )
+__children["FormatQuery"]["image"].setInput( __children["ImageReader"]["out"] )
+__children["FormatQuery"]["__uiPosition"].setValue( imath.V2f( -6.3312459, 2.28593731 ) )
+__children["Expression"]["__in"]["p0"].setInput( __children["FormatQuery"]["size"]["x"] )
+__children["Expression"]["__uiPosition"].setValue( imath.V2f( -14.8670864, 2.18593836 ) )
+__children["Expression"]["__engine"].setValue( 'OSL' )
+__children["Expression"]["__expression"].setValue( 'parent.__out.p0 = parent.__in.p0 - 7;' )
 
 
 del __children