tech-writing · amotl · Mar 3, 2025 · Mar 3, 2025 · Mar 3, 2025 · Mar 3, 2025
diff --git a/CHANGES.md b/CHANGES.md
@@ -9,6 +9,7 @@
   Markdown or YAML formats, available per `rapporto report`.
 - Shell (Slack/Weekly): Publish daily reports to Slack, in a per-week
   context, with hourly granularity, available per `rapporto notify`.
+- Slack/Markdown: Fixed encoding link titles including square brackets
 
 ## v0.3.0, 2025-02-24
 - Opsgenie: Added alert reporter. Thanks, @WalBah.
@@ -73,5 +74,5 @@
   "org:python author:AA-Turner created:2025-01-01..2025-01-31 is:pr"
   ```
   ```shell
-  rapporto ppp --organization=python --author=AA-Turner --when="2025-01-01..2025-01-31"
+  rapporto github activity --organization=python --author=AA-Turner --when="2025-01-01..2025-01-31"
   ```
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # Rapporto
 
-Harvest information from GitHub, Opsgenie, and Slack,
-and create reports in Markdown format. [DWIM](https://en.wikipedia.org/wiki/DWIM).
+Harvest information from GitHub, Opsgenie, and Slack, create reports in
+Markdown format, and publish them in different ways. [DWIM](https://en.wikipedia.org/wiki/DWIM).
 
 [![CI][badge-ci]][project-ci]
 [![Coverage][badge-coverage]][project-coverage]
@@ -19,7 +19,7 @@ See [Rapporto Installation].
 
 ## Usage
 
-See [Rapporto User Guide].
+See [Rapporto Sources] and [Rapporto Reports].
 
 ## Quick links
 
@@ -39,7 +39,8 @@ See [Rapporto User Guide].
 [License]: https://github.com/tech-writing/rapporto/blob/main/LICENSE
 [PyPI]: https://pypi.org/project/rapporto/
 [Rapporto Installation]: https://rapporto.readthedocs.io/install.html
-[Rapporto User Guide]: https://rapporto.readthedocs.io/guide/
+[Rapporto Sources]: https://rapporto.readthedocs.io/source/
+[Rapporto Reports]: https://rapporto.readthedocs.io/report/
 [Source code]: https://github.com/tech-writing/rapporto
 
 [badge-ci]: https://github.com/tech-writing/rapporto/actions/workflows/main.yml/badge.svg

diff --git a/docs/backlog.md b/docs/backlog.md
@@ -1,21 +1,14 @@
 # Backlog
 
 ## Iteration +1
-- Shell '25: Introduce _daily_ and _weekly_ operation modes / interfaces
-- Naming things: `source` vs. `sink` vs. Slack CLI domains
-- Project layout and docs: Bring up to speed
-- Docs: Generic page about `--when` option
 - Shell/Daily: Interleave CI reports
-- UI/Slack: Improve zapping
 - Aika: Fix bugs and refactor code
 - Pueblo: Fix bugs and refactor code
-- Configuration: Per `[tool]` section in `pyproject.toml`
-- UI/Slack: https://api.slack.com/messaging/files
-- UI/Slack: chat_scheduleMessage
-- Options: Program currently understands `--slack-token=`, but lacks `--github-token=`
-- UI/Console: Spice up Markdown output using `rich` and friends
+- `rapporto github activity` needs a section about "Top issues"
 
 ## Iteration +2
+- Options: Program currently understands `--slack-token=`, but lacks `--github-token=`
+- Configuration: Per `[tool]` section in `pyproject.toml`
 - GitHub/Actions: Currently lacks parameter `--when`
 - General: Summaries, using the excellent `llm` package
 - GitHub/Bugs: Add labels `blocked`, `blocked-by XXX`, `impediment`
@@ -26,9 +19,11 @@
 - GitHub: Search items with people assignments
 - GitHub/API: On errors, the JSON response includes the reason as an
   error message. However, it isn't displayed, yet.
+- GitHub: Report about stale issues
 - Options: Make `limit=100` configurable? Is paging needed?
 - `github-backup` can do "Exceeded rate limit of 5000 requests;
   waiting 77 seconds to reset". Do we also need it?
+- UI/Console: Spice up Markdown output using `rich` and friends
 
 ## Iteration +3
 - Data: Identify items with high conversation activity (comment frequency, etc.)
@@ -54,6 +49,8 @@
   >
   > [markdown-to-mrkdwn]: https://pypi.org/project/markdown-to-mrkdwn/
   > [Slack `mrkdwn` format]: https://api.slack.com/reference/surfaces/formatting#basic-formatting
+- UI/Slack: https://api.slack.com/messaging/files
+- UI/Slack: chat_scheduleMessage
 
 ## Done
 - Make it work.
@@ -81,3 +78,9 @@
 - Options: Parse time intervals using `aika`
 - Slack: Support for `mrkdwn` output
 - GitHub: Process `created` + `updated`, not just `created`
+- Shell '25: Introduce _daily_ and _weekly_ operation modes / interfaces
+- Docs: Generic page about `--when` option
+- Naming things: `source` vs. `sink` vs. Slack CLI domains
+- Project layout and docs: Bring up to speed
+- Docs: Caveats / Philosophy
+- UI/Slack: Improve zapping
diff --git a/docs/conf.py b/docs/conf.py
@@ -134,7 +134,7 @@
 # Configure sphinxext-opengraph
 ogp_site_url = "https://rapporto.readthedocs.io/"
 ogp_enable_meta_description = True
-# ogp_image = "http://example.org/image.png"
+ogp_image = "https://github.com/user-attachments/assets/bb775ff8-95dd-47f9-a593-37a04757e4d8"
 # ogp_description_length = 300
 
 

diff --git a/docs/index.md b/docs/index.md
@@ -2,17 +2,17 @@
 
 Harvest information from GitHub, Opsgenie, and Slack,
 create reports in Markdown format, and publish them
-in different ways. [DWIM].
+in different ways. [DWIM], with notable {ref}`caveats`.
 
 ```{toctree}
 :maxdepth: 1
 :hidden:
 
 install
-guide/index
+source/index
 report/index
 tool/index
-project
+project/index
 ```
 
 ## Features
@@ -28,6 +28,12 @@ project
     use it on many services like Discord, Discourse, GitHub, Slack,
     and many more.
 
+::::{attention}
+**With great power comes great responsibility.**
+Rapporto is a powerful tool, please use it
+{ref}`responsibly <caveats>`.
+::::
+
 ## Synopsis
 
 ### GitHub
@@ -37,28 +43,28 @@ project
 :::{tab-item} Actions
 ```{code-block} shell
 :caption: Report about CI failures on [GHA].
-rapporto gh actions --repository=acme/acme-examples
+rapporto github actions --repository=acme/acme-examples
 ```
 :::
 
 :::{tab-item} Activity
 ```{code-block} shell
 :caption: Report about user activity on [GitHub] in [PPP] format.
-rapporto gh activity --organization=python --author=AA-Turner --when="2025W04"
+rapporto github activity --organization=python --author=AA-Turner --when="2025W04"
 ```
 :::
 
 :::{tab-item} Attention
 ```{code-block} shell
 :caption: Report about bugs and similar important items on [GitHub].
-rapporto gh attention --organization=python --when="2025W07"
+rapporto github attention --organization=python --when="2025W07"
 ```
 :::
 
 :::{tab-item} Backup
 ```{code-block} shell
 :caption: Full GitHub project backup using [github-backup].
-rapporto gh backup --all --pull-details --prefer-ssh --token="${GH_TOKEN}" --repository=kotori daq-tools
+rapporto github backup --all --pull-details --prefer-ssh --token="${GH_TOKEN}" --repository=kotori daq-tools
 ```
 :::
 

diff --git a/docs/project/caveats.md b/docs/project/caveats.md
@@ -0,0 +1,34 @@
+(caveats)=
+# Caveats
+
+[![Image](https://github.com/user-attachments/assets/6e8ea47c-20fd-4d37-9245-76e6cb7306ae){w=480px}][BuzzFeed]
+
+_It's like the government is being run by BuzzFeed. [It's ridiculous!][BuzzFeed]._
+
+## Guardrails
+
+Rapporto provides much information on your fingertips suitable to haunt
+humans, by harassing them on any of the items emitted by this program,
+in one way or another. Don't do that.
+
+> In addition to, not invalidating the existing sections in Rapporto's
+> [license document], and with a strong emphasis like on topics about
+> Disclaimer of Warranties and Limitation of Liabilities, THIS SOFTWARE
+> MUST NOT BE USED TO JUDGE, RANK, OR TRACK PEOPLE, OR TO CREATE ANY
+> KINDS OF DOSSIERS ABOUT THEM, WHERE SUCH METRICS OR RANKINGS CAN
+> BE DERIVED FROM, WHICH COULD BE USED BY OTHERS FOR SIMILAR PURPOSES,
+> INCLUDING MACHINES.
+
+## Q & A
+
+> Q: What's the difference between a controller and a terrorist?
+> <br>
+> A: A terrorist at least has sympathisers.
+
+## Don't Panic
+
+![Image](https://github.com/user-attachments/assets/bb775ff8-95dd-47f9-a593-37a04757e4d8)
+
+
+[BuzzFeed]: https://www.youtube.com/watch?v=4xGUlG5Ck6c&t=105s
+[license document]: https://github.com/tech-writing/rapporto/blob/main/LICENSE
diff --git a/docs/project/index.md b/docs/project/index.md
@@ -0,0 +1,21 @@
+# Project
+
+Project information. This and that. Contributions are very much welcome.
+
+:::{rubric} Operations
+:::
+```{toctree}
+:maxdepth: 1
+
+caveats
+```
+
+:::{rubric} Development
+:::
+```{toctree}
+:maxdepth: 1
+
+Changelog <../changes>
+Backlog <../backlog>
+prior-art
+```
diff --git a/docs/project.md → docs/project/prior-art.md b/docs/project.md → docs/project/prior-art.md
@@ -1,21 +1,14 @@
-# Project
+# Prior art
 
-```{toctree}
-:maxdepth: 1
-
-Changelog <changes>
-Backlog <backlog>
-```
-
-## Prior art
+## Primary inspirations
 - https://github.com/saschpe/rapport
 - https://github.com/nedbat/dinghy
 - https://github.com/kneth/gh-utils
 - https://github.com/slackapi/slack-github-action
 - https://gist.github.com/Chandler/fb7a070f52883849de35
 - https://github.com/zach-snell/slack-export
 
-### More
+## More inspirations
 - https://github.com/badele/gitcheck
 - https://github.com/nlitsme/githubtool
 - https://github.com/badele/github-summary

diff --git a/docs/report/index.md b/docs/report/index.md
@@ -30,12 +30,12 @@ a given time interval.
 
 Please provide a valid GitHub token. This token is invalid.
 ```shell
-export GH_TOKEN=ghp_600VEZtdzinvalid7K2R86JTiKJAAp1wNwVP
+export GH_TOKEN="ghp_600VEZtdzinvalid7K2R86JTiKJAAp1wNwVP"
 ```
 
 Please provide a valid Slack API token. This token is invalid.
 ```bash
-export SLACK_TOKEN='xoxb-your-slack-bot-token'
+export SLACK_TOKEN="xoxb-your-slack-bot-token"
 ```
 Alternatively to using the environment variable, you can also use the
 `rapporto notify --slack-token=` command-line option.

diff --git a/docs/guide/github.md → docs/source/github.md b/docs/guide/github.md → docs/source/github.md
@@ -23,7 +23,7 @@ token (classic), that permits access to those scopes:
 
 Please provide a valid GitHub token. This token is invalid.
 ```shell
-export GH_TOKEN=ghp_600VEZtdzinvalid7K2R86JTiKJAAp1wNwVP
+export GH_TOKEN="ghp_600VEZtdzinvalid7K2R86JTiKJAAp1wNwVP"
 ```
 
 ### Options
@@ -38,29 +38,31 @@ expand the search scope.
 ### Actions report
 Report about activities of GitHub Actions workflow runs, mostly failing ones.
 ```shell
-rapporto gh actions --repository=acme/acme-examples
-rapporto gh actions --repositories-file=acme-repositories.txt
+rapporto github actions --repository="acme/acme-examples"
+rapporto github actions --repositories-file="acme-repositories.txt"
 ```
 
 ### Activity report
 Report about activities of individual authors.
 ```shell
-rapporto gh activity --organization=python --author=AA-Turner --when="2025-01-01..2025-01-31"
-rapporto gh activity --organization=python --author=AA-Turner --when="2025W04"
+rapporto github activity --organization="python" --author="AA-Turner" --when="2025-01-01..2025-01-31"
+rapporto github activity --organization="python" --author="AA-Turner" --when="2025W04"
 ```
 
 ### Attention report
 Report about important items that deserve your attention, bugs first.
 ```shell
-rapporto gh attention --organization=python --when="2025W07"
+rapporto github attention --organization="python" --when="2025W07"
 ```
 If you want to explore your personal repositories, please use the
 `--organization` option with your username, e.g. `--organization=AA-Turner`.
 
 ### Backup
 Full GitHub project backup using [github-backup].
 ```shell
-rapporto gh backup --all --pull-details --prefer-ssh --token="${GH_TOKEN}" --repository=kotori daq-tools
+rapporto github backup \
+  --all --pull-details --prefer-ssh --token="${GH_TOKEN}" \
+  --repository="kotori" daq-tools
 ```
 
 

diff --git a/docs/guide/index.md → docs/source/index.md b/docs/guide/index.md → docs/source/index.md
diff --git a/docs/guide/opsgenie.md → docs/source/opsgenie.md b/docs/guide/opsgenie.md → docs/source/opsgenie.md
diff --git a/docs/guide/slack.md → docs/source/slack.md b/docs/guide/slack.md → docs/source/slack.md
@@ -31,7 +31,7 @@ authentication token with access permissions to the required [OAuth scopes].
 
 Either define the authentication token as an environment variable,
 ```bash
-export SLACK_TOKEN='xoxb-your-slack-bot-token'
+export SLACK_TOKEN="xoxb-your-slack-bot-token"
 ```
 or use the `--slack-token` command-line option.
 

diff --git a/docs/tool/goof/index.md b/docs/tool/goof/index.md
@@ -7,7 +7,9 @@ Notify humans and machines, [DWIM].
 Goof supports Rapporto's "notify" subsystem. You can also use it in other
 programs, either using its Python API, or its command-line interface.
 
-## Guide
+## Notifiers
+
+Goof currently supports Slack as a notification target.
 
 ```{toctree}
 :maxdepth: 1

diff --git a/src/pueblo_goof/cli.py b/src/pueblo_goof/cli.py
@@ -57,15 +57,14 @@
     Send one or multiple Slack messages in Markdown format.
     """
 
-    zapper = Zapper(zap)
-    zapper.check()
-
     if not (channel or update or reply_to):
         raise click.UsageError("Please provide either 'channel' or 'update' or 'reply_to'")
 
     channel = channel or update or reply_to
 
     conversation = SlackConversation(api_token=ctx.meta["slack_token"], channel=channel)
+    zapper = Zapper(when=zap, action=conversation.delete)
+
     message_ids = []
     for msg in message:
         if msg == "-":
@@ -80,8 +79,7 @@
         message_ids.append(message_id)
 
     try:
-        if zapper.process():
-            conversation.delete()
+        zapper.process()
     except Exception as e:
         raise click.ClickException(f"The 'zap' operation failed: {e}") from e