Add an initial setup using Cog for README files
- ID
e04eda8- date
2023-12-25 23:33:30+00:00- author
Alex Chan <alex@alexwlchan.net>- parent
fc8a49f- message
Add an initial setup using Cog for README files- changed files
5 files, 133 additions, 79 deletions
Changed files
.github/workflows/test.yml (1116) → .github/workflows/test.yml (1222)
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index be9b28e..c96011d 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -35,6 +35,11 @@ jobs:
# by black and I don't have a strong opinion on, so I'm going to trust
# black and have flake8 ignore it.
flake8 --ignore=E501,W503
+
+ - name: Check README files with Cog
+ run: |
+ find . -name README.md | xargs cog --check
+
- name: Run tests
run: |
py.test aws/test_s3tree.py
cog_helpers.py (0) → cog_helpers.py (1346)
diff --git a/cog_helpers.py b/cog_helpers.py
new file mode 100644
index 0000000..0972a7b
--- /dev/null
+++ b/cog_helpers.py
@@ -0,0 +1,58 @@
+"""
+Some helper functions for generating the README files in this repo.
+In particular, it can take a list of scripts as a Python object, and
+create an HTML definition list that describes them in a human-readable way.
+
+Here Cog is Ned Batchelder's file generation tool, described here:
+https://nedbatchelder.com/code/cog
+"""
+
+import textwrap
+from typing import TypedDict
+
+import cog
+
+
+class ScriptWithName(TypedDict):
+ name: str
+ description: str
+
+
+class ScriptWithUsage(TypedDict):
+ usage: str
+ description: str
+
+
+Script = ScriptWithName | ScriptWithUsage
+
+
+def create_description_table(
+ folder_name: str,
+ scripts: list[Script],
+ repo_name: str = "alexwlchan/scripts",
+ primary_branch: str = "main",
+) -> None:
+ cog.outl("<dl>")
+
+ for s in scripts:
+ try:
+ name = s['name']
+ except KeyError:
+ name = s['usage'].split()[0]
+
+ try:
+ usage = textwrap.dedent(s['usage']).strip()
+ except KeyError:
+ usage = name
+
+ cog.outl("<dt>")
+ cog.outl(f"<a href=\"https://github.com/{repo_name}/blob/{primary_branch}/{folder_name}/{name}\">")
+ cog.outl(f"<code>{usage}</code>")
+ cog.outl("</a>")
+ cog.outl("</dt>")
+
+ cog.outl("<dd>")
+ cog.outl(s['description'])
+ cog.outl("</dd>")
+
+ cog.outl("</dl>")
macos/README.md (2515) → macos/README.md (2435)
diff --git a/macos/README.md b/macos/README.md
index 8369033..205c516 100644
--- a/macos/README.md
+++ b/macos/README.md
@@ -5,88 +5,76 @@ They rely on Mac-specific stuff and are unlikely to be useful on non-Mac systems
## The individual 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 – anything that can be easily recreated/reopened later
- </dd>
+<!-- [[[cog
- <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>
+import sys; sys.path.append("/Users/alexwlchan/repos/scripts")
+import cog_helpers
- <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>
+folder_name = "macos"
- <dt>
- <a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_focus_mode">
- <code>get_focus_mode [directory]</code>
- </a>
- </dt>
- <dd>
- returns the current Focus mode
- </dd>
+scripts = [
+ {
+ "name": "battery",
+ "description": "alias for <code>pmset -g batt</code>; reports the current battery level",
+ },
+ {
+ "name": "close_tabs",
+ "description": "close ephemeral tabs in Safari – basically, anything that can be easily recreated/reopened later."
+ },
+ {
+ "name": "find_processes_using_secure_input",
+ "description": "lists any processes using Secure Input, which can block apps like TextExpander"
+ },
+ {
+ "usage": "get_all_live_text [directory]",
+ "description": "get OCR'd text for all the images in a directory using Live Text"
+ },
+ {
+ "name": "get_focus_mode",
+ "description": "prints the current Focus mode"
+ },
+ {
+ "name": "get_live_text [image]",
+ "description": "get OCR'd text for a single image using Live Text"
+ },
+ {
+ "usage": "set_accent_colour (red|orange|yellow|green|blue|purple|pink|graphite)",
+ "description": "set the accent colour, as configured in the Appearance settings",
+ },
+ {
+ "usage": "sterilise [PATH]",
+ "description": "alias for <code>xattr -d com.apple.quarantine</code>"
+ },
+ {
+ "name": "unlock_keychain",
+ "description": """
+ 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>
+ """
+ }
+]
- <dt>
- <a href="https://github.com/alexwlchan/scripts/blob/main/macos/get_live_text">
- <code>get_live_text [image]</code>
- </a>
- </dt>
- <dd>
- get OCR'd text for a single image using Live Text
- </dd>
+cog_helpers.create_description_table(folder_name=folder_name, scripts=scripts)
- <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>
+<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>
</dl>
+<!-- [[[end]]] (checksum: fa3a0dacc7ecb411506845102787c6ae) -->
requirements.in (136) → requirements.in (143)
diff --git a/requirements.in b/requirements.in
index 0a71a0c..3c81161 100644
--- a/requirements.in
+++ b/requirements.in
@@ -1,6 +1,7 @@
attrs
black
boto3
+cogapp
flake8
httpx
humanize
requirements.txt (2393) → requirements.txt (2436)
diff --git a/requirements.txt b/requirements.txt
index 2e7ebd3..b0e82f5 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -32,6 +32,8 @@ click==8.1.7
# via
# black
# pip-tools
+cogapp==3.3.0
+ # via -r requirements.in
flake8==6.1.0
# via -r requirements.in
h11==0.14.0