docs: improve light entity documentation

docs/.gitignore

@@ -1,2 +1,2 @@
 _build
-_html
+*html*

docs/conf.py

@@ -39,6 +39,8 @@ templates_path = ['_templates']
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+# report broken references
+nitpicky = True
 
 # -- Options for HTML output -------------------------------------------------
 

docs/ericw-tools.py

@@ -54,6 +54,36 @@ def setup(app: Sphinx):
             indextemplate='pair: %s; light entity key',
             parse_node=parse_epair,
         )
+    app.add_object_type(
+        directivename='spotlight-key',
+        rolename='spotlight-key',
+        indextemplate='pair: %s; spotlight entity key',
+        parse_node=parse_epair,
+    )
+    app.add_object_type(
+        directivename='surflight-key',
+        rolename='surflight-key',
+        indextemplate='pair: %s; surface light entity key',
+        parse_node=parse_epair,
+    )
+    app.add_object_type(
+        directivename='projlight-key',
+        rolename='projlight-key',
+        indextemplate='pair: %s; projected texture light entity key',
+        parse_node=parse_epair,
+    )
+    app.add_object_type(
+        directivename='skylight-key',
+        rolename='skylight-key',
+        indextemplate='pair: %s; skylight entity key',
+        parse_node=parse_epair,
+    )
+    app.add_object_type(
+        directivename='sunlight-key',
+        rolename='sunlight-key',
+        indextemplate='pair: %s; sunlight entity key',
+        parse_node=parse_epair,
+    )
     app.add_object_type(
             directivename='classname',
             rolename='classname',

docs/light.rst

@@ -790,7 +790,7 @@ If used on func_detail* or func_group, a full qbsp pass need to be run.
    Integer. Default 0.
 
    Can be set to a nonzero value to make these brushes emit as surface lights
-   only from a light template with a matching :light-key:`_surflight_group` value.
+   only from a light template with a matching :surflight-key:`_surflight_group` value.
 
 .. bmodel-key:: "_lightcolorscale" "n"
 
@@ -805,6 +805,9 @@ Light entity keys can be used in any entity with a classname starting
 with the first five letters "light". E.g. "light", "light_globe",
 "light_flame_small_yellow", etc.
 
+Point Lights
+------------
+
 .. light-key:: "light" "n"
 
    Set the light intensity. Negative values are also allowed and will
@@ -821,7 +824,7 @@ with the first five letters "light". E.g. "light", "light_globe",
 
    Select an attenuation formaula for the light:
 
-   ::
+   .. code:: none
 
       0 => Linear attenuation (default)
       1 => 1/x attenuation
@@ -850,30 +853,6 @@ with the first five letters "light". E.g. "light", "light_globe",
    light. RGB component values are between 0 and 255 (between 0 and 1 is
    also accepted). Default is white light ("255 255 255").
 
-.. light-key:: "target" "name"
-
-   Turns the light into a spotlight, with the direction of light being
-   towards another entity with it's "targetname" key set to "name".
-
-.. light-key:: "mangle" "yaw pitch roll"
-
-   Turns the light into a spotlight and specifies the direction of light
-   using yaw, pitch and roll in degrees. Yaw specifies the angle around
-   the Z-axis from 0 to 359 degrees and pitch specifies the angle from
-   90 (straight up) to -90 (straight down). Roll has no effect, so use
-   any value (e.g. 0). Often easier than the "target" method.
-
-.. light-key:: "angle" "n"
-
-   Specifies the angle in degrees for a spotlight cone. Default 40.
-
-.. light-key:: "_softangle" "n"
-
-   Specifies the angle in degrees for an inner spotlight cone (must be
-   less than the "angle" cone. Creates a softer transition between the
-   full brightness of the inner cone to the edge of the outer cone.
-   Default 0 (disabled).
-
 .. light-key:: "targetname" "name"
 
    Turns the light into a switchable light, toggled by another entity
@@ -921,7 +900,49 @@ with the first five letters "light". E.g. "light", "light_globe",
    Number of lights to use for "_deviance". Default 16 (only used if
    "_deviance" is set).
 
-.. light-key:: "_surface" "texturename"
+.. light-key:: "_bouncescale" "n"
+
+   Scales the amount of light that is contributed by bounces. Default is
+   1.0, 0.0 disables bounce lighting for this light.
+
+.. light-key:: "_nostaticlight" "n"
+
+   Set to 1 to make the light compiler ignore this entity (prevents it
+   from casting any light). e.g. could be useful with rtlights.
+
+Spotlights
+----------
+
+Supports all keys from `Point Lights`_ in addition to the following:
+
+.. spotlight-key:: "target" "name"
+
+   Turns the light into a spotlight, with the direction of light being
+   towards another entity with it's "targetname" key set to "name".
+
+.. spotlight-key:: "mangle" "yaw pitch roll"
+
+   Turns the light into a spotlight and specifies the direction of light
+   using yaw, pitch and roll in degrees. Yaw specifies the angle around
+   the Z-axis from 0 to 359 degrees and pitch specifies the angle from
+   90 (straight up) to -90 (straight down). Roll has no effect, so use
+   any value (e.g. 0). Often easier than the "target" method.
+
+.. spotlight-key:: "angle" "n"
+
+   Specifies the angle in degrees for a spotlight cone. Default 40.
+
+.. spotlight-key:: "_softangle" "n"
+
+   Specifies the angle in degrees for an inner spotlight cone (must be
+   less than the "angle" cone. Creates a softer transition between the
+   full brightness of the inner cone to the edge of the outer cone.
+   Default 0 (disabled).
+
+Surface Lights
+--------------
+
+.. surflight-key:: "_surface" "texturename"
 
    Makes surfaces with the given texture name emit light, by using this
    light as a template which is copied across those surfaces. Lights are
@@ -929,118 +950,160 @@ with the first five letters "light". E.g. "light", "light_globe",
    apart and positioned 2 units above the surfaces.
 
    To restrict this surface light config to a subset of brushes with
-   the "texturename" texture applied, see the :light-key:`_surflight_group` key.
+   the "texturename" texture applied, see the :surflight-key:`_surflight_group` key.
 
-.. light-key:: "_surface_offset" "n"
+.. surflight-key:: "_surface_offset" "n"
 
-   Controls the offset lights are placed above surfaces for :light-key:`_surface`.
+   Controls the offset lights are placed above surfaces for :surflight-key:`_surface`.
    Default 2.
 
-.. light-key:: "_surface_spotlight" "n"
+.. surflight-key:: "_surface_spotlight" "n"
 
-   For a surface light template (i.e. a light with :light-key:`_surface` set),
+   For a surface light template (i.e. a light with :surflight-key:`_surface` set),
    setting this to "1" makes each instance into a spotlight, with the
    direction of light pointing along the surface normal. In other words,
    it automatically sets "mangle" on each of the generated lights.
 
-.. light-key:: "_surface_radiosity" "n"
+.. surflight-key:: "_surface_radiosity" "n"
 
-   Whether to use Q1-style surface subdivision (0) or Q2-style 
+   Whether to use Q1-style surface subdivision (0) or Q2-style
    surface radiosity (1) on this light specifically.
 
-   Use in conjunction with :light-key:`_surface`.
+   Use in conjunction with :surflight-key:`_surface`.
 
-   The default can be changed for all surface lights in a map with 
+   The default can be changed for all surface lights in a map with
    worldspawn key :worldspawn-key:`_surflight_radiosity`.
 
-.. light-key:: "_surflight_group" "n"
+.. surflight-key:: "_surflight_group" "n"
 
    Integer, default 0.
 
-   For use with :light-key:`_surface` lights.
+   For use with :surflight-key:`_surface` lights.
 
    Can be set to a nonzero value to restrict
    this surface light template to only emit from brushes with a matching
    :bmodel-key:`_surflight_group` value.
 
-.. light-key:: "_project_texture" "texture"
+
+Projected Texture Lights
+------------------------
+
+.. projlight-key:: "_project_texture" "texture"
 
    Specifies that a light should project this texture. The texture must
    be used in the map somewhere.
 
-.. light-key:: "_project_mangle" "yaw pitch roll"
+   .. todo:: This is a qbsp limitation which could be fixed
+
+.. projlight-key:: "_project_mangle" "yaw pitch roll"
 
    Specifies the yaw/pitch/roll angles for a texture projection
    (overriding mangle).
 
-.. light-key:: "_project_fov" "n"
+.. projlight-key:: "_project_fov" "n"
 
    Specifies the fov angle for a texture projection. Default 90.
 
-.. light-key:: "_bouncescale" "n"
 
-   Scales the amount of light that is contributed by bounces. Default is
+Sun Light
-   1.0, 0.0 disables bounce lighting for this light.
+---------
 
-.. light-key:: "_sun" "n"
+Also called directional light. Emitted from sky faces.
+
+.. sunlight-key:: "_sun" "n"
 
    Set to 1 to make this entity a sun, as an alternative to using the
-   sunlight worldspawn keys. If the light targets an info_null entity,
+   sunlight worldspawn keys.
+
+.. sunlight-key:: "target" "t"
+
+   If the light targets an info_null entity,
    the direction towards that entity sets sun direction. The light
    itself is disabled, so it can be placed anywhere in the map.
 
-   The following light properties correspond to these sunlight settings:
+.. sunlight-key:: "mangle" "yaw pitch roll"
 
-   ::
+   Alternate way of specifying sunlight direction.
 
-      light       => _sunlight
+   Equivalent to worldspawn key :worldspawn-key:`_sunlight_mangle`.
-      mangle      => _sunlight_mangle
-      deviance    => _sunlight_penumbra
-      _color      => _sunlight_color
-      _dirt       => _sunlight_dirt
-      _anglescale => _anglescale
-      style       => flicker style for styled sunlight
-      targetname  => targetname for switchable sunlight
-      _suntexture => this sunlight is only emitted from faces with this texture name
 
-.. light-key:: "_sunlight2" "n"
+.. sunlight-key:: "light" "n"
+
+   Equivalent to worldspawn key :worldspawn-key:`_sunlight`.
+
+.. sunlight-key:: "color" "r g b"
+
+   Equivalent to worldspawn key :worldspawn-key:`_sunlight_color`.
+
+.. sunlight-key:: "deviance" "n"
+
+   Equivalent to worldspawn key :worldspawn-key:`_sunlight_penumbra`.
+
+.. sunlight-key:: "_dirt" "n"
+
+   Equivalent to worldspawn key :worldspawn-key:`_sunlight_dirt`.
+
+.. sunlight-key:: "_anglescale" "n"
+
+   Equivalent to worldspawn key :worldspawn-key:`_anglescale`.
+
+.. sunlight-key:: "style" "n"
+
+   Flicker style for styled sunlight.
+
+.. sunlight-key:: "targetname" "name"
+
+   Targetname for switchable sunlight.
+
+.. sunlight-key:: "_suntexture" "texname"
+
+   This sunlight is only emitted from faces with this texture name. Default is to be emitted from all sky textures.
+
+
+Sky Light
+---------
+
+Hemisphere shaped light emitted from sky faces.
+
+.. skylight-key:: "_sunlight2" "n"
 
    Set to 1 to make this entity control the upper dome lighting emitted
    from sky faces, as an alternative to the worldspawn key :worldspawn-key:`_sunlight2`.
    The light entity itself is disabled, so it can be placed anywhere in
    the map.
 
-   The following light properties correspond to these sunlight settings:
+.. skylight-key:: "_sunlight3" "n"
 
-   light
+   Same as :skylight-key:`_sunlight2`, but makes this sky light come from the lower hemisphere.
-      _sunlight2
 
-   _color
+.. skylight-key:: "light" "n"
-      _sunlight2_color
 
-   _dirt
+   Sets the dome light brightness. Equivalent to worldspawn key :worldspawn-key:`_sunlight2`.
-      _sunlight2_dirt
 
-   _anglescale
+.. skylight-key:: "_color" "r g b"
-      _anglescale
 
-   style
+   Sets the dome light color. Equivalent to worldspawn key :worldspawn-key:`_sunlight2_color`.
-      flicker style for styled dome light
 
-   targetname
+.. skylight-key:: "_dirt" "n"
-      targetname for switchable sunlight
 
-   _suntexture
+   Equivalent to worldspawn key :worldspawn-key:`_sunlight2_dirt`.
-      this sunlight is only emitted from faces with this texture name
 
-.. light-key:: "_sunlight3" "n"
+.. skylight-key:: "_anglescale" "n"
 
-   Same as :light-key:`_sunlight2`, but for the lower hemisphere.
+   Equivalent to worldspawn key :worldspawn-key:`_anglescale`.
 
-.. light-key:: "_nostaticlight" "n"
+.. skylight-key:: "style" "n"
+
+   Flicker style for styled sky light.
+
+.. skylight-key:: "targetname" "name"
+
+   Targetname for switchable skylight.
+
+.. skylight-key:: "_suntexture" "texname"
+
+   This sky light is only emitted from faces with this texture name. Default is to be emitted from all sky textures.
 
-   Set to 1 to make the light compiler ignore this entity (prevents it
-   from casting any light). e.g. could be useful with rtlights.
 
 Lighting Channels
 =================

docs/requirements.in

@@ -1,2 +1,3 @@
-sphinx==6.2.1
+sphinx==7.2.6
-furo==2023.3.27
+furo==2024.1.29
+sphinx-autobuild==2024.2.4

docs/requirements.txt

@@ -4,58 +4,71 @@
 #
 #    pip-compile requirements.in
 #
-alabaster==0.7.13
+alabaster==0.7.16
     # via sphinx
-babel==2.12.1
+babel==2.14.0
     # via sphinx
-beautifulsoup4==4.12.2
+beautifulsoup4==4.12.3
     # via furo
-certifi==2023.7.22
+certifi==2024.2.2
     # via requests
-charset-normalizer==3.1.0
+charset-normalizer==3.3.2
     # via requests
-docutils==0.19
+colorama==0.4.6
+    # via
+    #   sphinx
+    #   sphinx-autobuild
+docutils==0.20.1
     # via sphinx
-furo==2023.3.27
+furo==2024.1.29
     # via -r requirements.in
-idna==3.4
+idna==3.6
     # via requests
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.3
     # via sphinx
-markupsafe==2.1.2
+livereload==2.6.3
+    # via sphinx-autobuild
+markupsafe==2.1.5
     # via jinja2
-packaging==23.1
+packaging==23.2
     # via sphinx
-pygments==2.15.1
+pygments==2.17.2
     # via
     #   furo
     #   sphinx
 requests==2.31.0
     # via sphinx
+six==1.16.0
+    # via livereload
 snowballstemmer==2.2.0
     # via sphinx
-soupsieve==2.4.1
+soupsieve==2.5
     # via beautifulsoup4
-sphinx==6.2.1
+sphinx==7.2.6
     # via
     #   -r requirements.in
     #   furo
+    #   sphinx-autobuild
     #   sphinx-basic-ng
-sphinx-basic-ng==1.0.0b1
+sphinx-autobuild==2024.2.4
+    # via -r requirements.in
+sphinx-basic-ng==1.0.0b2
     # via furo
-sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-applehelp==1.0.8
     # via sphinx
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==1.0.6
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-htmlhelp==2.0.5
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==1.0.7
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.10
     # via sphinx
-urllib3==2.0.7
+tornado==6.4
+    # via livereload
+urllib3==2.2.0
     # via requests