From 27d7c3acc64009f0f4e361a4c3da891e9df1b239 Mon Sep 17 00:00:00 2001
From: Myk <myk002@yahoo.com>
Date: Tue, 5 Jul 2022 14:05:34 -0700
Subject: [PATCH] Myk sample command help (#2238)

* add example tool documentation in proposed format

* refine Tools.rst
---
 conf.py                  |  6 +-----
 docs/Tools.rst           | 13 +++++++++++++
 docs/tools/cromulate.rst | 34 ++++++++++++++++++++++++++++++++++
 index.rst                |  1 +
 4 files changed, 49 insertions(+), 5 deletions(-)
 create mode 100644 docs/Tools.rst
 create mode 100644 docs/tools/cromulate.rst

diff --git a/conf.py b/conf.py
index 71ba65fb7..53b192467 100644
--- a/conf.py
+++ b/conf.py
@@ -66,11 +66,7 @@ def dfhack_keybind_role_func(role, rawtext, text, lineno, inliner,
     """Custom role parser for DFHack default keybinds."""
     roles.set_classes(options)
     if text not in KEYBINDS:
-        msg = inliner.reporter.error(
-            'no keybinding for {} in dfhack.init-example'.format(text),
-            line=lineno)
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
+        return [], []
     newnode = nodes.paragraph()
     for cmd, key, ctx in KEYBINDS[text]:
         n = nodes.paragraph()
diff --git a/docs/Tools.rst b/docs/Tools.rst
new file mode 100644
index 000000000..15c5f878e
--- /dev/null
+++ b/docs/Tools.rst
@@ -0,0 +1,13 @@
+.. _tools-index:
+
+############
+DFHack Tools
+############
+
+These are the DFHack commands you can run.
+
+.. toctree::
+   :titlesonly:
+   :glob:
+
+   /docs/tools/*
diff --git a/docs/tools/cromulate.rst b/docs/tools/cromulate.rst
new file mode 100644
index 000000000..ca07ae0ca
--- /dev/null
+++ b/docs/tools/cromulate.rst
@@ -0,0 +1,34 @@
+cromulate
+=========
+
+Tags: productivity, unit, adventure
+:dfhack-keybind:`cromulate`
+
+Collects all widgets into a frobozz electric cromufiler. You might want to do
+this if you discover that your widgets have become decromulated. It is safe to
+run this command periodically even if you are unsure if that's the case.
+
+Usage::
+
+    cromulate [all|here] [<options>]
+
+When run without parameters, it lists all your widgets. Add the ``all`` keyword
+to collect all widgets into the cromufiler, or the ``here`` keyword to just
+collect those under the cursor.
+
+Options:
+
+:``-d``, ``--destroy``:
+    Destroy the widgets instead of collecting them into the cromufiler.
+:``-q``, ``--quiet``:
+    Don't display any informational output. Errors will still be printed to the
+    console.
+
+Examples:
+
+- ``cromulate``
+    Lists all widgets and their positions
+- ``cromlate all``
+    Gather all widgets into the cromufiler
+- ``cromulate here --destroy``
+    Destroys the widgets under the cursor
diff --git a/index.rst b/index.rst
index 2e5454f40..63ab02a86 100644
--- a/index.rst
+++ b/index.rst
@@ -32,6 +32,7 @@ User Manual
    /docs/Core
    /docs/Plugins
    /docs/Scripts
+   /docs/Tools
    /docs/guides/index
    /docs/index-about
    /docs/index-dev