Documentation: Improve and refactor, accompanying naming things

... and subsystem changes.

Author: amotl

CHANGES.md

@@ -6,9 +6,9 @@
 - Goof: Added wrapper around Slack conversations, available per
   CLI `goof slack send`.
 - Shell (Reports/Daily+Weekly): Generate daily and weekly reports in
-  Markdown or YAML formats.
+  Markdown or YAML formats, available per `rapporto report`.
 - Shell (Slack/Weekly): Publish daily reports to Slack, in a per-week
-  context, with hourly granularity.
+  context, with hourly granularity, available per `rapporto notify`.
 
 ## v0.3.0, 2025-02-24
 - Opsgenie: Added alert reporter. Thanks, @WalBah.

docs/guide/github.md

@@ -19,15 +19,21 @@ token (classic), that permits access to those scopes:
 
 ## Usage
 
-### Introduction
+### Authentication
 
 Please provide a valid GitHub token. This token is invalid.
 ```shell
 export GH_TOKEN=ghp_600VEZtdzinvalid7K2R86JTiKJAAp1wNwVP
 ```
 
-Note that many options are optional. Just omit them in order to expand the
-search scope.
+### Options
+
+The [`--when`](#when-option) command-line option accepts a wide range of
+values to adjust the time interval. You can also omit the option completely,
+in which case the program will assume the current day or calendar week.
+
+Note that many other options are also optional. Just omit them in order to
+expand the search scope.
 
 ### Actions report
 Report about activities of GitHub Actions workflow runs, mostly failing ones.

docs/guide/index.md

@@ -1,6 +1,6 @@
-# User Guide
+# Sources
 
-Learn how to use Rapporto for acquiring information and reporting.
+Use Rapporto for acquiring information from different APIs.
 
 ```{toctree}
 :maxdepth: 1
@@ -9,7 +9,6 @@ Learn how to use Rapporto for acquiring information and reporting.
 github
 opsgenie
 slack
-options
 ```
 
 ::::{grid} 3
@@ -48,16 +47,4 @@ Tap into the Opsgenie API and generate reports in Markdown format.
 Tap into the Slack API and export threads into Markdown format.
 :::
 
-:::{grid-item-card}
-:link: options
-:link-type: doc
-:class-body: sd-text-center sd-fs-3 sd-font-weight-bold
-:class-footer: sd-fs-6
-Options
-
-{fas}`gears;sd-text-white fa-2xl`
-+++
-Program options, input and output.
-:::
-
 ::::

docs/guide/opsgenie.md

@@ -14,34 +14,32 @@ In order to authenticate with the Opsgenie API, you will need an Opsgenie API ke
 
 ## Usage
 
+### Authentication
+
 Either define the authentication token as an environment variable,
 ```bash
 export OPSGENIE_API_KEY="your-api-key"
 ```
 or use the `--api-key` command-line option.
 
-### Alert report
+### Options
 
-Generate report about Opsgenie alerts.
+The [`--when`](#when-option) command-line option accepts a wide range of
+values to adjust the time interval. You can also omit the option completely,
+in which case the program will assume the current day or calendar week.
 
-Report about the previous seven days.
-```shell
-rapporto opsgenie export-alerts --when="-7d"
-```
+### Alert report
+
+Generate report about Opsgenie alerts in Markdown format.
 
 Report about yesterday.
 ```shell
 rapporto opsgenie export-alerts --when="yesterday"
 ```
 
-Report about the previous week.
-```shell
-rapporto opsgenie export-alerts --when="last week"
-```
-
-Report about the current week.
+Report about the previous seven days.
 ```shell
-rapporto opsgenie export-alerts --when="this week"
+rapporto opsgenie export-alerts --when="-7d"
 ```
 
 Describe the time interval by start time and duration in days.

docs/guide/options.md

@@ -27,6 +27,8 @@ authentication token with access permissions to the required [OAuth scopes].
 
 ## Usage
 
+### Authentication
+
 Either define the authentication token as an environment variable,
 ```bash
 export SLACK_TOKEN='xoxb-your-slack-bot-token'
@@ -37,7 +39,8 @@ or use the `--slack-token` command-line option.
 
 Export Slack conversation thread into Markdown document.
 ```shell
-rapporto slack export https://acme.slack.com/archives/D018V8WDABA/p1738873838427919
+rapporto slack export \
+  "https://acme.slack.com/archives/D018V8WDABA/p1738873838427919"
 ```
 
 

docs/guide/slack.md

@@ -10,8 +10,8 @@ in different ways. [DWIM].
 
 install
 guide/index
-sink/index
 report/index
+tool/index
 project
 ```
 

docs/index.md

@@ -1,4 +1,4 @@
-# Installation
+# Install
 
 We recommend to use the [uv] package manager for installing or running Rapporto.
 ```shell

docs/install.md

@@ -1,4 +1,4 @@
-# Project Information
+# Project
 
 ```{toctree}
 :maxdepth: 1

docs/project.md

@@ -1,21 +1,30 @@
 # Reports
 
-Daily reports and notifications, using a weekly context and a hourly
-granularity, fluently converging to Slack conversations, at your disposal.
+Produce daily reports and notifications, using a weekly context and an hourly
+granularity, fluently converging into Slack conversations, at your disposal.
 
-
-## Usage
+## Overview
 
 The reporting section includes two subsystems. Both produce reports about
 a given time interval.
 
-:`rapporto report`: Produce reports in Markdown or YAML formats. 
+:`rapporto report`: Produce reports in Markdown or YAML format.
 :`rapporto notify`: Produce reports and submit to Slack conversation.
 
-:::{tip}
-In the examples below, you can also omit the `--when` option completely.
-In this case, the current day or week will be assumed.
-:::
+> I am currently producing Markdown with Rapporto, similar to how you would
+> use a [static site generator] like a traditional tool in tech-writing,
+> for example Docusaurus, Hugo, Jekyll, MkDocs, Sphinx, or [many others].
+>
+> Contrary to a generator that produces HTML output,
+> Rapporto does not render Markdown or reStructuredText into HTML, which
+> is then displayed in the browser. Instead, information is acquired from
+> API calls, converted into Markdown, then displayed, for example, on Slack.
+ 
+> Using Rapporto to drive threaded conversations on Slack tries to behave
+> like a static site generator, producing idempotent message content, even
+> when spanning multiple messages.
+
+## Usage
 
 ### Authentication
 
@@ -31,33 +40,57 @@ 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.
 
+### Options
+
+The [`--when`](#when-option) command-line option accepts a wide range of
+values to adjust the time interval. You can also omit the option completely,
+in which case the program will assume the current day or calendar week.
 
-## Reports
+## Markdown Reports
 
 Report about given day.
 ```shell
-rapporto report --github-organization=acme daily --when=2025-02-28
+rapporto report --github-organization="acme" daily --when="2025-02-28"
+```
+
+Report about given calendar week.
+```shell
+rapporto report --github-organization="acme" weekly --when="2025W09"
 ```
 
-Report about given week.
+Print yesterday's report.
 ```shell
-rapporto report --github-organization=acme weekly --when=2025W09
+rapporto report --github-organization="acme" daily --when="yesterday"
 ```
 
+Print today's report in YAML format.
+```shell
+rapporto report --github-organization="acme" --format="yaml" daily
+```
 
-## Conversations
+
+## Slack Conversations
 
 Report and notify about current calendar week.
 ```shell
-rapporto notify --slack-channel="janitor-bot" weekly
+rapporto notify --gh-org="acme" --slack-channel="janitor-bot" weekly
 ```
 
 Report and notify about given calendar week.
 ```shell
-rapporto notify --slack-channel="janitor-bot" weekly --week=2025W09
+rapporto notify --gh-org="acme" --slack-channel="janitor-bot" weekly --week="2025W09"
 ```
 
 For development purposes, zap messages after pressing enter.
 ```shell
-rapporto notify --slack-channel="janitor-bot" weekly --zap=key
+rapporto notify --gh-org="acme" --slack-channel="janitor-bot" weekly --zap=key
 ```
+
+:::{tip}
+The command-line option `--gh-org` is a shorthand version of `--github-organization`.
+You can use it to save a few keystrokes.
+:::
+
+
+[many others]: https://github.com/myles/awesome-static-generators
+[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator