doc textshader: Generate documentation for built-in textshaders.

renpy/common/00textshader_ren.py

@@ -57,8 +57,8 @@ renpy.register_textshader(
     """,
 
     doc="""
-    The typewriter text shader makes text appear slowly, as if it were being
-    type out by a typewriter.
+    The typewriter text shader handles slow text by making the text appear one character at a time, as if it were being
+    typed out by a typewriter.
     """
 )
 
@@ -93,8 +93,8 @@ renpy.register_textshader(
     u__duration=10.0,
 
     doc="""
-    The dissolve text shader makes text appear slowly, dissolving in from
-    the start to the end.
+    The dissolve text shader handles text by dissolving it in slowly, with the start dissolving in first, and the
+    end dissolving in last.
 
     `u__duration`
         The number of characters that will be changing alpha at a time.  If set to
@@ -104,7 +104,6 @@ renpy.register_textshader(
 
 renpy.register_textshader(
     "slowalpha",
-    include_default=False,
 
     variables="""
     uniform float u__alpha
@@ -121,9 +120,9 @@ vec4 l__color = gl_FragColor;
     u__alpha=0.2,
 
     doc="""
-    The slowalpha shows slow text that has yet to be revealed with a non-zero alpha.
-    This is generally used in combination with other text shaders, typewriter
-    or wave, that reveal text slowly.
+    The slowalpha shader is intended to be used with another slow text shader, like typewriter or dissolve.
+    It causes the text that has yet to be revealed to be drawn with an alpha value of `u__alpha`, rather than
+    being invisible.
 
     `u__alpha`
         The alpha value of the text that has not been revealed yet.
@@ -160,7 +159,8 @@ renpy.register_textshader(
     u__duration=10.0,
 
     doc="""
-    The flip text shader flips the text around its center, revealing it slowly
+    The flip shader flips slow text by flipping the text horizontally, with the start flipping in first,
+    and the end flipping in last.
 
     `u__duration`
         The number of characters that will be changing alpha at a time.  If set to
@@ -170,7 +170,7 @@ renpy.register_textshader(
 
 renpy.register_textshader(
     "zoom",
-    include_default=True,
+    include_default=False,
     adjust_function=adjust_duration,
 
     variables="""
@@ -195,7 +195,7 @@ renpy.register_textshader(
     u__duration=10.0,
 
     doc="""
-    The zoom text shader zooms in on the text.
+    The zoom text shader handles slow text to cause it to zoom in from an initial size of `u__zoom` to full size.
 
     `u__zoom`
         The initial amount of zoom to apply to a character when it first starts
@@ -226,7 +226,7 @@ renpy.register_textshader(
     redraw=0.0,
 
     doc="""
-    The jitter text shader jitters moves the text to random positions
+    The jitter text shader moves the text to random positions
     relative to where it would be normally drawn. The position changes
     once per frame.
 
@@ -361,10 +361,10 @@ renpy.register_textshader(
     u__scale=(1.0, 1.0),
 
     doc="""
-    Applys a texture to the text, one line at a time. The texture is aligned with
-    the left sideo of the text. The vertical center of the texture is aligned with
-    the baseline of the text - this meas that most of the texture will not
-    be visible.
+    Multiplies the text with a texture, one line at a time. The texture is aligned with
+    the left side of the text. The vertical center of the texture is aligned with
+    the baseline of the text - this meas that most of the lower half of the texture
+    will not be visible.
 
     `u__texture`
         The texture to multiply the text by.

sphinx/build.sh

@@ -16,13 +16,10 @@ python ../renpy.py . || ../renpy3.sh .
 rm -Rf ../doc-web/_images || true
 rm -Rf ../doc/_images || true
 
-# Build the full web documentation.
 sphinx-build -E -a source ../doc-web &
 
 # Build the included-with-Ren'Py documentation, if not running interactively.
-if [ ! -t 0 ]; then
-    RENPY_NO_FIGURES=1 sphinx-build -E -a source ../doc 2>/dev/null
-fi
+RENPY_NO_FIGURES=1 sphinx-build -E -a source ../doc 2>/dev/null
 
 # Wait for both builds to finish.
 wait

sphinx/game/script.rpy

@@ -14,6 +14,7 @@ init 1000000 python:
     incdir = os.path.join(srcdir, 'inc')
 
     shaderdoc.shaders(incdir=incdir)
+    shaderdoc.textshaders(incdir=incdir)
 
     doc.scan_section("", renpy.store)
     doc.scan_section("renpy.", renpy)

sphinx/game/shaderdoc.py

@@ -4,6 +4,7 @@ import os
 import renpy
 import textwrap
 
+import re
 
 def shaders(incdir="source/inc"):
 
@@ -80,3 +81,50 @@ def shaders(incdir="source/inc"):
                 p("Fragment shader (priority %d)::" % prio)
 
                 indented(s)
+
+
+
+
+def textshaders(incdir="source/inc"):
+
+    with open(incdir + "/builtintextshaders", "w") as outf:
+
+        for name, shader in sorted(renpy.config.textshaders.items()):
+            print("---", name)
+
+            if not shader.doc:
+                continue
+
+            doc = textwrap.dedent(shader.doc)
+
+            uniforms = { }
+
+            for u, v in shader.uniforms:
+                uniforms[u] = v
+
+            def replace_uniform(m):
+                u = m.group(1)[1:-1]
+                value = uniforms[u]
+
+                u = u.replace("u_textshader_" + name + "_", "u__")
+
+                if isinstance(value, renpy.display.displayable.Displayable):
+                    value = "..."
+                else:
+                    value = repr(value)
+
+                return "`{}` = {}".format(u, value)
+
+            doc = re.sub(r"(`u_.*?`)", replace_uniform, doc)
+
+            outf.write(".. textshader:: {}\n".format(name))
+            outf.write("\n")
+
+            for i in doc.split("\n"):
+                outf.write("    {}\n".format(i))
+
+            if not shader.include_default:
+                outf.write("\n")
+                outf.write("    Using this shader will prevent the default text shader from being used.\n")
+
+            outf.write("\n")

sphinx/source/renpydoc.py

@@ -201,6 +201,7 @@ def setup(app):
     app.add_object_type("transform-property", "tpref", "single: %s (transform property)")
     app.add_object_type("screen-property", "scpref", "single: %s (screen property)", parse_node=parse_scpref_node)
     app.add_object_type("text-tag", "tt", "single: %s (text tag)")
+    app.add_object_type("textshader", "textshader" "single: %s (text shader)")
 
     add_index(app, "std", "style-property", "Style Property Index")
     add_index(app, "std", "transform-property", "Transform Property Index")

sphinx/source/textshaders.rst

@@ -81,7 +81,7 @@ The value of a uniform can be:
 * A color, beginning with #. (For example, #f00 or #ff0000 for red.) This
   creates a a vec4 corresponding to that color. This color will be
   premultiplied by its alpha channel.
-* A :doc:`displayable <displayables>`that will be
+* A :doc:`displayable <displayables>` that will be
   used as a texture. This creates a sampler2D that can be used to sample
   the texture.
 
@@ -123,3 +123,10 @@ shader based on a preference. ::
 
     define config.default_textshader = "default"
     define config.textshader_callbacks["default"] = get_default_textshader
+
+Built-In Text Shaders
+=====================
+
+Ren'Py includes a number of built-in text shaders. These are:
+
+.. include:: inc/builtintextshaders