Skip to main content

Merge pull request #7 from alexwlchan/more-cog

ID
3e1bb06
date
2023-12-26 12:51:48+00:00
author
Alex Chan <alex@alexwlchan.net>
parents
1dcc7c7, 266084c
message
Merge pull request #7 from alexwlchan/more-cog

Continue using Cog to generate the README files
changed files
5 files, 327 additions, 211 deletions

Changed files

cog_helpers.py (1366) → cog_helpers.py (1585)

diff --git a/cog_helpers.py b/cog_helpers.py
index 84c7de6..e8e5bca 100644
--- a/cog_helpers.py
+++ b/cog_helpers.py
@@ -26,15 +26,19 @@ class ScriptWithUsage(TypedDict):
 Script = ScriptWithName | ScriptWithUsage
 
 
+def outl(s: str, indent: int = 0):
+    cog.outl(textwrap.indent(s, prefix=" " * indent))
+
+
 def create_description_table(
     folder_name: str,
     scripts: list[Script],
     repo_name: str = "alexwlchan/scripts",
     primary_branch: str = "main",
 ) -> None:
-    cog.outl("<dl>")
+    outl("<dl>")
 
-    for s in scripts:
+    for i, s in enumerate(scripts, start=1):
         try:
             name = s["name"]
         except KeyError:
@@ -45,16 +49,20 @@ def create_description_table(
         except KeyError:
             usage = name
 
-        cog.outl("<dt>")
-        cog.outl(
-            f'<a href="https://github.com/{repo_name}/blob/{primary_branch}/{folder_name}/{name}">'
+        outl("<dt>", indent=2)
+        outl(
+            f'<a href="https://github.com/{repo_name}/blob/{primary_branch}/{folder_name}/{name}">',
+            indent=4,
         )
-        cog.outl(f"<code>{usage}</code>")
-        cog.outl("</a>")
-        cog.outl("</dt>")
+        outl(f"<code>{usage}</code>", indent=6)
+        outl("</a>", indent=4)
+        outl("</dt>", indent=2)
+
+        outl("<dd>", indent=2)
+        outl(textwrap.dedent(s["description"]).strip(), indent=4)
+        outl("</dd>", indent=2)
 
-        cog.outl("<dd>")
-        cog.outl(textwrap.dedent(s["description"]).strip())
-        cog.outl("</dd>")
+        if i != len(scripts):
+            outl("")
 
-    cog.outl("</dl>")
+    outl("</dl>")

macos/README.md (5128) → macos/README.md (5436)

diff --git a/macos/README.md b/macos/README.md
index 2f20392..cceac94 100644
--- a/macos/README.md
+++ b/macos/README.md
@@ -71,96 +71,106 @@ cog_helpers.create_description_table(folder_name=folder_name, scripts=scripts)
 
 ]]]-->
 <dl>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/battery">
-<code>battery</code>
-</a>
-</dt>
-<dd>
-alias for <code>pmset -g batt</code>; reports the current battery level
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/close_tabs">
-<code>close_tabs</code>
-</a>
-</dt>
-<dd>
-close ephemeral tabs in Safari – basically, anything that can be easily recreated/reopened later.
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/find_processes_using_secure_input">
-<code>find_processes_using_secure_input</code>
-</a>
-</dt>
-<dd>
-lists any processes using Secure Input, which can block apps like TextExpander
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_all_live_text">
-<code>get_all_live_text [directory]</code>
-</a>
-</dt>
-<dd>
-get OCR'd text for all the images in a directory using Live Text
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_focus_mode">
-<code>get_focus_mode</code>
-</a>
-</dt>
-<dd>
-prints the current Focus mode
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_frontmost_window_title">
-<code>get_frontmost_window_title [APP_NAME]</code>
-</a>
-</dt>
-<dd>
-prints the title of the frontmost window in the named app. This is particularly useful when working with apps that don't support AppleScript.
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_live_text [image]">
-<code>get_live_text [image]</code>
-</a>
-</dt>
-<dd>
-get OCR'd text for a single image using Live Text
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/obnote">
-<code>obnote</code>
-</a>
-</dt>
-<dd>
-print the path to the note I currently have open in [Obsidian](https://obsidian.md/), if any.
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/set_accent_colour">
-<code>set_accent_colour (red|orange|yellow|green|blue|purple|pink|graphite)</code>
-</a>
-</dt>
-<dd>
-set the accent colour, as configured in the Appearance settings
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/sterilise">
-<code>sterilise [PATH]</code>
-</a>
-</dt>
-<dd>
-alias for <code>xattr -d com.apple.quarantine</code>
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/macos/unlock_keychain">
-<code>unlock_keychain</code>
-</a>
-</dt>
-<dd>
-alias for <code>security unlock-keychain ~/Library/Keychains/login.keychain</code>; unlocks the login keychain
-<p>
-  The login keychain normally gets unlocked by the OS when you log into your account; this is for when I'm accessing a Mac over SSH.
-</p>
-</dd>
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/battery">
+      <code>battery</code>
+    </a>
+  </dt>
+  <dd>
+    alias for <code>pmset -g batt</code>; reports the current battery level
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/close_tabs">
+      <code>close_tabs</code>
+    </a>
+  </dt>
+  <dd>
+    close ephemeral tabs in Safari – basically, anything that can be easily recreated/reopened later.
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/find_processes_using_secure_input">
+      <code>find_processes_using_secure_input</code>
+    </a>
+  </dt>
+  <dd>
+    lists any processes using Secure Input, which can block apps like TextExpander
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_all_live_text">
+      <code>get_all_live_text [directory]</code>
+    </a>
+  </dt>
+  <dd>
+    get OCR'd text for all the images in a directory using Live Text
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_focus_mode">
+      <code>get_focus_mode</code>
+    </a>
+  </dt>
+  <dd>
+    prints the current Focus mode
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_frontmost_window_title">
+      <code>get_frontmost_window_title [APP_NAME]</code>
+    </a>
+  </dt>
+  <dd>
+    prints the title of the frontmost window in the named app. This is particularly useful when working with apps that don't support AppleScript.
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_live_text [image]">
+      <code>get_live_text [image]</code>
+    </a>
+  </dt>
+  <dd>
+    get OCR'd text for a single image using Live Text
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/obnote">
+      <code>obnote</code>
+    </a>
+  </dt>
+  <dd>
+    print the path to the note I currently have open in [Obsidian](https://obsidian.md/), if any.
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/set_accent_colour">
+      <code>set_accent_colour (red|orange|yellow|green|blue|purple|pink|graphite)</code>
+    </a>
+  </dt>
+  <dd>
+    set the accent colour, as configured in the Appearance settings
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/sterilise">
+      <code>sterilise [PATH]</code>
+    </a>
+  </dt>
+  <dd>
+    alias for <code>xattr -d com.apple.quarantine</code>
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/macos/unlock_keychain">
+      <code>unlock_keychain</code>
+    </a>
+  </dt>
+  <dd>
+    alias for <code>security unlock-keychain ~/Library/Keychains/login.keychain</code>; unlocks the login keychain
+    <p>
+      The login keychain normally gets unlocked by the OS when you log into your account; this is for when I'm accessing a Mac over SSH.
+    </p>
+  </dd>
 </dl>
-<!-- [[[end]]] (checksum: f7e1feec3b74bd4146f0910828465cf3) -->
+<!-- [[[end]]] (checksum: f83d99f7ee2b7ffd54416fcc1b1cb01e) -->

terraform/README.md (2776) → terraform/README.md (4454)

diff --git a/terraform/README.md b/terraform/README.md
index 49ce415..3b168dc 100644
--- a/terraform/README.md
+++ b/terraform/README.md
@@ -6,6 +6,60 @@ These scripts are all related to [Terraform], the infrastructure-as-code tool we
 
 ## The individual scripts
 
+<!-- [[[cog
+
+# This adds the root of the repo to the PATH, which has cog_helpers.py
+from os.path import abspath, dirname
+import sys
+
+sys.path.append(abspath(dirname(dirname("."))))
+
+import cog_helpers
+
+folder_name = "terraform"
+
+scripts = [
+    {
+        "name": "tf",
+        "description": "alias for `terraform`",
+    },
+    {
+        "name": "tfi",
+        "description": """
+        alias for <a href="https://developer.hashicorp.com/terraform/cli/commands/init"><code>terraform init</code></a>
+        """,
+    },
+    {
+        "name": "tfp",
+        "description": """
+        alias for <a href="https://developer.hashicorp.com/terraform/cli/commands/plan"><code>terraform plan -out=tfplan</code></a>.
+        I run this before making any changes, so I can review what Terraform is about to do.
+        """,
+    },
+    {
+        "name": "tfa",
+        "description": """
+        alias for <a href="https://developer.hashicorp.com/terraform/cli/commands/apply"><code>terraform apply terraform.plan</code></a>.
+        I only run this after I’ve reviewed the proposed changes from <code>tfp</code>.
+        """,
+    },
+    {
+        "name": "tfmv",
+        "description": """
+        alias for <a href="https://developer.hashicorp.com/terraform/cli/commands/state/mv"><code>terraform state mv</code></a>
+        """,
+    },
+    {
+        "name": "tflint",
+        "description": """
+        alias for the <a href="https://github.com/terraform-linters/tflint">tflint linter</a>, but running inside a Docker container
+        """,
+    },
+]
+
+cog_helpers.create_description_table(folder_name=folder_name, scripts=scripts)
+
+]]]-->
 <dl>
   <dt>
     <a href="https://github.com/alexwlchan/scripts/blob/main/terraform/tf">
@@ -13,7 +67,7 @@ These scripts are all related to [Terraform], the infrastructure-as-code tool we
     </a>
   </dt>
   <dd>
-    alias for <code>terraform</code>
+    alias for `terraform`
   </dd>
 
   <dt>
@@ -31,7 +85,7 @@ These scripts are all related to [Terraform], the infrastructure-as-code tool we
     </a>
   </dt>
   <dd>
-    alias for <a href="https://developer.hashicorp.com/terraform/cli/commands/plan"><code>terraform plan -out=terraform.plan</code></a>.
+    alias for <a href="https://developer.hashicorp.com/terraform/cli/commands/plan"><code>terraform plan -out=tfplan</code></a>.
     I run this before making any changes, so I can review what Terraform is about to do.
   </dd>
 
@@ -63,6 +117,7 @@ These scripts are all related to [Terraform], the infrastructure-as-code tool we
     alias for the <a href="https://github.com/terraform-linters/tflint">tflint linter</a>, but running inside a Docker container
   </dd>
 </dl>
+<!-- [[[end]]] (checksum: b9d70deb03a18bfd0a84a1a3ee918977) -->
 
 ## Choosing between `terraform` and `run_terraform.sh`

text/README.md (5777) → text/README.md (6120)

diff --git a/text/README.md b/text/README.md
index 7f45da8..2a208f6 100644
--- a/text/README.md
+++ b/text/README.md
@@ -90,107 +90,118 @@ cog_helpers.create_description_table(folder_name=folder_name, scripts=scripts)
 
 ]]]-->
 <dl>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/body">
-<code>body -n [LINENO] [PATH]</code>
-</a>
-</dt>
-<dd>
-print the nth line of a file.
-This is meant to fill a gap between the Unix utilities `head` and `tail`.
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/fix_twitter_thread.py">
-<code>fix_twitter_thread.py [PATH]</code>
-</a>
-</dt>
-<dd>
-when I copy/paste a Twitter thread into Obsidian, this does some 
-initial tidying up of the formatting for me.
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/fix_whitespace">
-<code>fix_whitespace [PATH]</code>
-</a>
-</dt>
-<dd>
-when I copy/paste text into Obsidian from th web, this cleans up some of the extraneous whitespace.
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/midline">
-<code>midline [PATH]</code>
-</a>
-</dt>
-<dd>
-print the line in the middle of a file, e.g. if the file has 5 lines, it prints line 3
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/natsize">
-<code>natsize < [NUMBER]</code>
-</a>
-</dt>
-<dd>
-prints a numeric file size as a human-readable string, e.g. `32036032` becomes `32.0 MB`
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/noplaylist.py">
-<code>noplaylist.py < [URL]</code>
-</a>
-</dt>
-<dd>
-removes the `list` query parameter from a YouTube URL; I use it with `youtube-dl`
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/r">
-<code>r</code>
-</a>
-</dt>
-<dd>
-an alias for `rg`, aka <a href="https://geoff.greer.fm/ag/">the Silver Searcher</a>. (Yes, I really am too lazy to type two whole characters.)
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/randline">
-<code>randline [NUMBER] < [PATH]</code>
-</a>
-</dt>
-<dd>
-prints randomly selected lines from the given text. If `NUMBER` is unspecified, it prints a single line.
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/reverse">
-<code>reverse < [PATH]</code>
-</a>
-</dt>
-<dd>
-prints the lines of text, but in reverse order.
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/sumsizes.py">
-<code>sumsizes.py < [PATH]</code>
-</a>
-</dt>
-<dd>
-prints a human-readable data size for the numbers passed on stdin.
-
-    $ echo -e '100\n 201287\n 3190817' | sumsizes
-    3.4MB
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/tally">
-<code>tally < [PATH]</code>
-</a>
-</dt>
-<dd>
-prints a tally of lines in the given text.
-</dd>
-<dt>
-<a href="https://github.com/alexwlchan/scripts/blob/main/text/echo">
-<code>echo [STRING] | utf8info</code>
-</a>
-</dt>
-<dd>
-read UTF-8 on stdin and print out the raw Unicode "
-"codepoints. This is a Docker wrapper around <a href="https://github.com/lunasorcery/utf8info">a tool of the same name</a> by @lunasorcery.
-</dd>
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/body">
+      <code>body -n [LINENO] [PATH]</code>
+    </a>
+  </dt>
+  <dd>
+    print the nth line of a file.
+    This is meant to fill a gap between the Unix utilities `head` and `tail`.
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/fix_twitter_thread.py">
+      <code>fix_twitter_thread.py [PATH]</code>
+    </a>
+  </dt>
+  <dd>
+    when I copy/paste a Twitter thread into Obsidian, this does some 
+    initial tidying up of the formatting for me.
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/fix_whitespace">
+      <code>fix_whitespace [PATH]</code>
+    </a>
+  </dt>
+  <dd>
+    when I copy/paste text into Obsidian from th web, this cleans up some of the extraneous whitespace.
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/midline">
+      <code>midline [PATH]</code>
+    </a>
+  </dt>
+  <dd>
+    print the line in the middle of a file, e.g. if the file has 5 lines, it prints line 3
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/natsize">
+      <code>natsize < [NUMBER]</code>
+    </a>
+  </dt>
+  <dd>
+    prints a numeric file size as a human-readable string, e.g. `32036032` becomes `32.0 MB`
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/noplaylist.py">
+      <code>noplaylist.py < [URL]</code>
+    </a>
+  </dt>
+  <dd>
+    removes the `list` query parameter from a YouTube URL; I use it with `youtube-dl`
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/r">
+      <code>r</code>
+    </a>
+  </dt>
+  <dd>
+    an alias for `rg`, aka <a href="https://geoff.greer.fm/ag/">the Silver Searcher</a>. (Yes, I really am too lazy to type two whole characters.)
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/randline">
+      <code>randline [NUMBER] < [PATH]</code>
+    </a>
+  </dt>
+  <dd>
+    prints randomly selected lines from the given text. If `NUMBER` is unspecified, it prints a single line.
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/reverse">
+      <code>reverse < [PATH]</code>
+    </a>
+  </dt>
+  <dd>
+    prints the lines of text, but in reverse order.
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/sumsizes.py">
+      <code>sumsizes.py < [PATH]</code>
+    </a>
+  </dt>
+  <dd>
+    prints a human-readable data size for the numbers passed on stdin.
+
+        $ echo -e '100\n 201287\n 3190817' | sumsizes
+        3.4MB
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/tally">
+      <code>tally < [PATH]</code>
+    </a>
+  </dt>
+  <dd>
+    prints a tally of lines in the given text.
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/text/echo">
+      <code>echo [STRING] | utf8info</code>
+    </a>
+  </dt>
+  <dd>
+    read UTF-8 on stdin and print out the raw Unicode "
+    "codepoints. This is a Docker wrapper around <a href="https://github.com/lunasorcery/utf8info">a tool of the same name</a> by @lunasorcery.
+  </dd>
 </dl>
-<!-- [[[end]]] (checksum: 1ac648df181fdf4aea491bce61f10523) -->
\ No newline at end of file
+<!-- [[[end]]] (checksum: 6abfdf25169d3fba58601dec88f4bd9f) -->
\ No newline at end of file

textexpander/README.md (791) → textexpander/README.md (1695)

diff --git a/textexpander/README.md b/textexpander/README.md
index d70e24b..f9c3141 100644
--- a/textexpander/README.md
+++ b/textexpander/README.md
@@ -4,9 +4,40 @@ These scripts I invoke as text expansion macros in [TextExpander](https://textex
 
 ## The individual scripts
 
+<!-- [[[cog
+
+# This adds the root of the repo to the PATH, which has cog_helpers.py
+from os.path import abspath, dirname
+import sys
+
+sys.path.append(abspath(dirname(dirname("."))))
+
+import cog_helpers
+
+folder_name = "textexpander"
+
+scripts = [
+    {
+        "name": "get_mastodon_text.py",
+        "description": """
+        print a Markdown-formatted blockquote of a Mastodon I've got open in Safari, suitable for pasting into Obsidian
+        """,
+    },
+    {
+        "name": "get_safari_url.py",
+        "description": """
+        print the URL in my frontmost Safari window.
+        This makes a couple of tweaks to tidy up the URL, e.g. remove tracking parameters and tidy up some Jekyll stuff for my personal site.
+        """,
+    },
+]
+
+cog_helpers.create_description_table(folder_name=folder_name, scripts=scripts)
+
+]]]-->
 <dl>
   <dt>
-    <a href="https://github.com/alexwlchan/scripts/blob/main/obsidian/get_mastodon_text.py">
+    <a href="https://github.com/alexwlchan/scripts/blob/main/textexpander/get_mastodon_text.py">
       <code>get_mastodon_text.py</code>
     </a>
   </dt>
@@ -15,7 +46,7 @@ These scripts I invoke as text expansion macros in [TextExpander](https://textex
   </dd>
 
   <dt>
-    <a href="https://github.com/alexwlchan/scripts/blob/main/obsidian/get_safari_url.py">
+    <a href="https://github.com/alexwlchan/scripts/blob/main/textexpander/get_safari_url.py">
       <code>get_safari_url.py</code>
     </a>
   </dt>
@@ -24,3 +55,4 @@ These scripts I invoke as text expansion macros in [TextExpander](https://textex
     This makes a couple of tweaks to tidy up the URL, e.g. remove tracking parameters and tidy up some Jekyll stuff for my personal site.
   </dd>
 </dl>
+<!-- [[[end]]] (checksum: 92cb9f2e13db3a692bf3b95b32c5c773) -->