docs: drop custom envvar directive

The custom envvar directive is strange. It overloads the global
namespace, where there's already a well-known envvar directive, but the
envvar role won't resolve to envvars defined using the custom directive.

It's not really critical to declare the type and default value here, and
many descriptions already include this. Let's just use the plain one,
and let the description take care of the details where needed.

Reviewed-by: Yonggang Luo <luoyonggang@gmail.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/19593>

diff --git a/docs/_exts/formatting.py b/docs/_exts/formatting.py
index c7322d4..0276625 100644 (file)
--- a/docs/_exts/formatting.py
+++ b/docs/_exts/formatting.py
@@ -9,18 +9,6 @@ import sphinx.addnodes
 from sphinx.util.nodes import split_explicit_title
 from docutils import nodes, utils
 
-def parse_envvar(env, sig, signode):
-    envvar, t, default = sig.split(" ", 2)
-    envvar = envvar.strip().upper()
-    t = "Type: %s" % t.strip(" <>").lower()
-    default = "Default: %s" % default.strip(" ()")
-    signode += sphinx.addnodes.desc_name(envvar, envvar)
-    signode += docutils.nodes.Text(' ')
-    signode += sphinx.addnodes.desc_type(t, t)
-    signode += docutils.nodes.Text(', ')
-    signode += sphinx.addnodes.desc_annotation(default, default)
-    return envvar
-
 def parse_opcode(env, sig, signode):
     opcode, desc = sig.split("-", 1)
     opcode = opcode.strip().upper()
@@ -46,8 +34,6 @@ def ext_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
     return [pnode], []
 
 def setup(app):
-    app.add_object_type("envvar", "envvar", "%s (environment variable)",
-        parse_envvar)
     app.add_object_type("opcode", "opcode", "%s (TGSI opcode)",
         parse_opcode)
     app.add_role('ext', ext_role)

diff --git a/docs/drivers/d3d12.rst b/docs/drivers/d3d12.rst
index 7d2adca..604fd8b 100644 (file)
--- a/docs/drivers/d3d12.rst
+++ b/docs/drivers/d3d12.rst
@@ -15,7 +15,9 @@ Debugging
 There's a few tools that are useful for debugging D3D12, such as these
 environment variables:
 
-.. envvar:: D3D12_DEBUG <flags> ("")
+.. envvar:: D3D12_DEBUG
+
+   Accepts the following comma-separated list of flags:
 
    ``verbose``
       Enable verbose output to stdout
@@ -34,7 +36,9 @@ environment variables:
    ``gpuvalidator``
       Enable `GPU validator`_
 
-.. envvar:: DXIL_DEBUG <flags> ("")
+.. envvar:: DXIL_DEBUG
+
+   Accepts the following comma-separated list of flags:
 
    ``verbose``
       Enable verbose output to stdout
@@ -53,7 +57,7 @@ Utilities
 
 Environment variables that control the behavior of the D3D12 driver.
 
-.. envvar:: MESA_D3D12_DEFAULT_ADAPTER_NAME <string> ("")
+.. envvar:: MESA_D3D12_DEFAULT_ADAPTER_NAME
 
    Specifies a substring to search for when choosing a default adapter to
    run on. The first adapter matching the substring is chosen. The substring

diff --git a/docs/drivers/lima.rst b/docs/drivers/lima.rst
index 2380074..cec4144 100644 (file)
--- a/docs/drivers/lima.rst
+++ b/docs/drivers/lima.rst
@@ -62,7 +62,7 @@ Environment variables
 These are some Lima-specific environment variables that may aid in
 debugging. None of this is required for normal use.
 
-.. envvar:: LIMA_DEBUG <flags> ("")
+.. envvar:: LIMA_DEBUG
 
   accepts the following comma-separated list of flags:
 
@@ -92,19 +92,19 @@ debugging. None of this is required for normal use.
     disable multi job optimization
 
 
-.. envvar:: LIMA_CTX_NUM_PLB <int> (None)
+.. envvar:: LIMA_CTX_NUM_PLB
 
   set number of PLB per context (used for development purposes)
 
-.. envvar:: LIMA_PLB_MAX_BLK <int> (None)
+.. envvar:: LIMA_PLB_MAX_BLK
 
   set PLB max block (used for development purposes)
 
-.. envvar:: LIMA_PPIR_FORCE_SPILLING <int> (None)
+.. envvar:: LIMA_PPIR_FORCE_SPILLING
 
   force spilling of variables in PPIR (used for development purposes)
 
-.. envvar:: LIMA_PLB_PP_STREAM_CACHE_SIZE <int> (None)
+.. envvar:: LIMA_PLB_PP_STREAM_CACHE_SIZE
 
   set PP stream cache size (used for development purposes)
 

diff --git a/docs/drivers/zink.rst b/docs/drivers/zink.rst
index 9778ef2..747e6ca 100644 (file)
--- a/docs/drivers/zink.rst
+++ b/docs/drivers/zink.rst
@@ -253,7 +253,9 @@ Debugging
 There's a few tools that are useful for debugging Zink, like this environment
 variable:
 
-.. envvar:: ZINK_DEBUG <flags> ("")
+.. envvar:: ZINK_DEBUG
+
+  Accepts the following comma-separated list of flags:
 
   ``nir``
     Print the NIR form of all shaders to stderr.

diff --git a/docs/gallium/debugging.rst b/docs/gallium/debugging.rst
index 1d3aa06..801e87f 100644 (file)
--- a/docs/gallium/debugging.rst
+++ b/docs/gallium/debugging.rst
@@ -15,42 +15,42 @@ program from that console.
 Common
 """"""
 
-.. envvar:: GALLIUM_PRINT_OPTIONS <bool> (false)
+.. envvar:: GALLIUM_PRINT_OPTIONS
 
-   This option controls if the debug variables should be printed to stderr. This
-   is probably the most useful variable, since it allows you to find which
-   variables a driver uses.
+   This boolean option controls if the debug variables should be printed to
+   stderr.  This is probably the most useful variable, since it allows you to
+   find which variables a driver uses.
 
-.. envvar:: GALLIUM_TRACE <string> ("")
+.. envvar:: GALLIUM_TRACE
 
    If set, this variable will cause the :ref:`trace` output to be written to the
    specified file. Paths may be relative or absolute; relative paths are relative
    to the working directory.  For example, setting it to "trace.xml" will cause
    the trace to be written to a file of the same name in the working directory.
 
-.. envvar:: GALLIUM_TRACE_TC <bool> (false)
+.. envvar:: GALLIUM_TRACE_TC
 
    If enabled while :ref:`trace` is active, this variable specifies that the threaded context
    should be traced for drivers which implement it. By default, the driver thread is traced,
    which will include any reordering of the command stream from threaded context.
 
-.. envvar:: GALLIUM_TRACE_TRIGGER <string> ("")
+.. envvar:: GALLIUM_TRACE_TRIGGER
 
    If set while :ref:`trace` is active, this variable specifies a filename to monitor.
    Once the file exists (e.g., from the user running 'touch /path/to/file'), a single
    frame will be recorded into the trace output.
    Paths may be relative or absolute; relative paths are relative to the working directory.
 
-.. envvar:: GALLIUM_DUMP_CPU <bool> (false)
+.. envvar:: GALLIUM_DUMP_CPU
 
-   Dump information about the current CPU that the driver is running on.
+   Enable dumping of information about the current CPU that the driver is running on.
 
-.. envvar:: TGSI_PRINT_SANITY <bool> (false)
+.. envvar:: TGSI_PRINT_SANITY
 
-   Gallium has a built-in shader sanity checker.  This option controls whether
-   the shader sanity checker prints its warnings and errors to stderr.
+   Gallium has a built-in shader sanity checker.  This boolean option controls
+   whether the shader sanity checker prints its warnings and errors to stderr.
 
-.. envvar:: DRAW_USE_LLVM <bool> (false)
+.. envvar:: DRAW_USE_LLVM
 
    Whether the :ref:`Draw` module will attempt to use LLVM for vertex and geometry shaders.
 
@@ -58,7 +58,7 @@ Common
 GL State tracker-specific
 """""""""""""""""""""""""
 
-.. envvar:: ST_DEBUG <flags> (0x0)
+.. envvar:: ST_DEBUG
 
    Debug :ref:`flags` for the GL state tracker.
 
@@ -66,27 +66,27 @@ GL State tracker-specific
 Driver-specific
 """""""""""""""
 
-.. envvar:: I915_DEBUG <flags> (0x0)
+.. envvar:: I915_DEBUG
 
    Debug :ref:`flags` for the i915 driver.
 
-.. envvar:: I915_NO_HW <bool> (false)
+.. envvar:: I915_NO_HW
 
    Stop the i915 driver from submitting commands to the hardware.
 
-.. envvar:: I915_DUMP_CMD <bool> (false)
+.. envvar:: I915_DUMP_CMD
 
    Dump all commands going to the hardware.
 
-.. envvar:: LP_DEBUG <flags> (0x0)
+.. envvar:: LP_DEBUG
 
    Debug :ref:`flags` for the LLVMpipe driver.
 
-.. envvar:: LP_NUM_THREADS <int> (number of CPUs)
+.. envvar:: LP_NUM_THREADS
 
    Number of threads that the LLVMpipe driver should use.
 
-.. envvar:: FD_MESA_DEBUG <flags> (0x0)
+.. envvar:: FD_MESA_DEBUG
 
    Debug :ref:`flags` for the Freedreno driver.