Mesa (master): gallium/docs: Add formatting for envvar role; change debugging.

[Corbin Simpson]

Module: Mesa
Branch: master
Commit: bf357aedffd659e43ef9ceefa875c08991a5f46d
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=bf357aedffd659e43ef9ceefa875c08991a5f46d

Author: Corbin Simpson <MostAwesomeDude at gmail.com>
Date:   Sun Aug 15 03:05:18 2010 -0700

gallium/docs: Add formatting for envvar role; change debugging.

Per Jakob's request. Not super-pretty, but it's a good point for modding
later.

---

 src/gallium/docs/source/conf.py            |    2 +-
 src/gallium/docs/source/debugging.rst      |   24 ++++++++++----------
 src/gallium/docs/source/exts/formatting.py |   31 ++++++++++++++++++++++++++++
 src/gallium/docs/source/exts/tgsi.py       |   17 ---------------
 4 files changed, 44 insertions(+), 30 deletions(-)

diff --git a/src/gallium/docs/source/conf.py b/src/gallium/docs/source/conf.py
index 99e6652..0846e7d 100644
--- a/src/gallium/docs/source/conf.py
+++ b/src/gallium/docs/source/conf.py
@@ -22,7 +22,7 @@ sys.path.append(os.path.abspath('exts'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.pngmath', 'tgsi']
+extensions = ['sphinx.ext.pngmath', 'formatting']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/src/gallium/docs/source/debugging.rst b/src/gallium/docs/source/debugging.rst
index 74f51bc..f29bf53 100644
--- a/src/gallium/docs/source/debugging.rst
+++ b/src/gallium/docs/source/debugging.rst
@@ -15,36 +15,36 @@ program from that console.
 Common
 """"""
 
-GALLIUM_PRINT_OPTIONS <bool> (false)
+.. envvar:: GALLIUM_PRINT_OPTIONS <bool> (false)
 
 This options controls if the debug variables should be printed to stderr.
 This is probably the most usefull variable since it allows you to find
 which variables a driver responds to.
 
-GALLIUM_RBUG <bool> (false)
+.. envvar:: GALLIUM_RBUG <bool> (false)
 
 Controls if the :ref:`rbug` should be used.
 
-GALLIUM_TRACE <string> ("")
+.. envvar:: GALLIUM_TRACE <string> ("")
 
 If not set tracing is not used, if set it will write the output to the file
 specifed by the variable. So setting it to "trace.xml" will write the output
 to the file "trace.xml".
 
-GALLIUM_DUMP_CPU <bool> (false)
+.. envvar:: GALLIUM_DUMP_CPU <bool> (false)
 
 Dump information about the current cpu that the driver is running on.
 
-TGSI_PRINT_SANITY <bool> (false)
+.. envvar:: TGSI_PRINT_SANITY <bool> (false)
 
 Gallium has a inbuilt shader sanity checker, this option controls if results
 from it should be printed. This include warnings such as unused variables.
 
-DRAW_USE_LLVM <bool> (false)
+.. envvar:: DRAW_USE_LLVM <bool> (false)
 
 Should the :ref:`draw` module use llvm for vertex and geometry shaders.
 
-ST_DEBUG <flags> (0x0)
+.. envvar:: ST_DEBUG <flags> (0x0)
 
 Debug :ref:`flags` for the GL state tracker.
 
@@ -52,23 +52,23 @@ Debug :ref:`flags` for the GL state tracker.
 Driver specific
 """""""""""""""
 
-I915_DEBUG <flags> (0x0)
+.. envvar:: I915_DEBUG <flags> (0x0)
 
 Debug :ref:`flags` for the i915 driver.
 
-I915_NO_HW <bool> (false)
+.. envvar:: I915_NO_HW <bool> (false)
 
 Stop the i915 driver from submitting commands to the hardware.
 
-I915_DUMP_CMD <bool> (false)
+.. envvar:: I915_DUMP_CMD <bool> (false)
 
 Dump all commands going to the hardware.
 
-LP_DEBUG <flags> (0x0)
+.. envvar:: LP_DEBUG <flags> (0x0)
 
 Debug :ref:`flags` for the llvmpipe driver.
 
-LP_NUM_THREADS <int> (num cpus)
+.. envvar:: LP_NUM_THREADS <int> (num cpus)
 
 Number of threads that the llvmpipe driver should use.
 
diff --git a/src/gallium/docs/source/exts/formatting.py b/src/gallium/docs/source/exts/formatting.py
new file mode 100644
index 0000000..14865f3
--- /dev/null
+++ b/src/gallium/docs/source/exts/formatting.py
@@ -0,0 +1,31 @@
+# formatting.py
+# Sphinx extension providing formatting for Gallium-specific data
+# (c) Corbin Simpson 2010
+# Public domain to the extent permitted; contact author for special licensing
+
+import docutils.nodes
+import sphinx.addnodes
+
+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 += sphinx.addnodes.desc_type(t, t)
+    signode += sphinx.addnodes.desc_annotation(default, default)
+    return envvar
+
+def parse_opcode(env, sig, signode):
+    opcode, desc = sig.split("-", 1)
+    opcode = opcode.strip().upper()
+    desc = " (%s)" % desc.strip()
+    signode += sphinx.addnodes.desc_name(opcode, opcode)
+    signode += sphinx.addnodes.desc_annotation(desc, desc)
+    return opcode
+
+def setup(app):
+    app.add_description_unit("envvar", "envvar", "%s (environment variable)",
+        parse_envvar)
+    app.add_description_unit("opcode", "opcode", "%s (TGSI opcode)",
+        parse_opcode)
diff --git a/src/gallium/docs/source/exts/tgsi.py b/src/gallium/docs/source/exts/tgsi.py
deleted file mode 100644
index e92cd5c..0000000
--- a/src/gallium/docs/source/exts/tgsi.py
+++ /dev/null
@@ -1,17 +0,0 @@
-# tgsi.py
-# Sphinx extension providing formatting for TGSI opcodes
-# (c) Corbin Simpson 2010
-
-import docutils.nodes
-import sphinx.addnodes
-
-def parse_opcode(env, sig, signode):
-    opcode, desc = sig.split("-", 1)
-    opcode = opcode.strip().upper()
-    desc = " (%s)" % desc.strip()
-    signode += sphinx.addnodes.desc_name(opcode, opcode)
-    signode += sphinx.addnodes.desc_annotation(desc, desc)
-    return opcode
-
-def setup(app):
-    app.add_description_unit("opcode", "opcode", "%s (TGSI opcode)", parse_opcode)