After the repo has been renamed to express its larger intent (#13)

* Add support for command help to readme to inject levels of headers.
* That allows multiple tools to contribute to the same one doc.
* Some renaming.

README.header.txt

@@ -1,7 +1,7 @@
-# CircleCI tools
+# MBO-tools
 
 Continuous integration:
 [![Test](https://github.com/helly25/circleci/actions/workflows/main.yml/badge.svg)](https://github.com/helly25/circleci/actions/workflows/main.yml),
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/helly25/circleci).
 
-WIP
+# CircleCI

README.md

@@ -1,20 +1,20 @@
-# CircleCI tools
+# MBO-tools
 
 Continuous integration:
 [![Test](https://github.com/helly25/circleci/actions/workflows/main.yml/badge.svg)](https://github.com/helly25/circleci/actions/workflows/main.yml),
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/helly25/circleci).
 
-WIP
+# CircleCI
 
 A simple [CircleCI API](https://circleci.com) client that fetches workflow
 stats from the CircleCI API server and writes them as a CSV file.
 
-# Usage
+## Usage
 ```
 bazel run //circleci:workflows -- <command> [args...]
 ```
 
-## Commands
+### Commands
 * combine:            Read multiple files generated by `workflow.py fetch` and combine them.
 * fetch:              Fetch workflow data from the CircleCI API server and writes them as a CSV file.
 * fetch_details:      Given a workflow CSV file, fetch details for each workflow (slow).
@@ -27,12 +27,12 @@ bazel run //circleci:workflows -- <command> [args...]
 Most file based parameters transparently support gzip and bz2 compression when
 they have a '.gz' or '.bz2' extension respectively.
 
-## For command specific help use
+### For command specific help use
 ```
 bazel run //circleci:workflows -- <command> --help.
 ```
 
-## Command combine
+### Command combine
 
 Read multiple files generated by `workflow.py fetch` and combine them.
 
@@ -87,7 +87,7 @@ bazel run //circleci:workflows -- combine --output=/tmp/circleci.csv "${PWD}/dat
 > Whether to indicate progress (defaults to True if
 > `--fetch_workflow_details` is active).
 
-## Command fetch
+### Command fetch
 
 Fetch workflow data from the CircleCI API server and writes them as a CSV
 file.
@@ -178,7 +178,7 @@ bazel run //circleci:workflows -- fetch --output "${PWD}/data/circleci_workflows
 
 > Whether workflow details should automatically be added.
 
-## Command fetch_details
+### Command fetch_details
 
 Given a workflow CSV file, fetch details for each workflow (slow).
 
@@ -226,7 +226,7 @@ bazel run //circleci:workflows -- fetch_details --input "${PWD}/data/circleci_wo
 
 > Whether to indicate progress.
 
-## Command filter
+### Command filter
 
 Read CSV files generated from `workflow.py fetch` and filters them.
 
@@ -284,7 +284,7 @@ bazel run //circleci:workflows -- filter --workflow default_workflow,pre_merge -
 > Accept only the listed days of the week as indexed 1=Monday through
 > 7=Sunday (ISO notation).
 
-## Command request_branches
+### Command request_branches
 
 Read and display the list of branches for `workflow` from CircleCI API.
 
@@ -328,7 +328,7 @@ bazel run //circleci:workflows -- request_branches
 > The name of the workflow to read. Multiple workflows can be read by
 > separating with comma.
 
-## Command request_workflow
+### Command request_workflow
 
 Given a workflow ID return its details.
 
@@ -368,7 +368,7 @@ bazel run //circleci:workflows -- request_workflow --workflow_id <ID>
 
 > Workflow ID to request.
 
-## Command request_workflows
+### Command request_workflows
 
 Read and display the list of workflow names from CircleCI API.
 

circleci/BUILD

@@ -80,7 +80,12 @@ genrule(
     srcs = ["//:README.header.txt"],
     outs = ["readme.txt"],
     cmd = """
-        ./$(location :workflows) help --help_output_mode=markdown --all_commands --prefix="$(location //:README.header.txt)" > "$@"
+        ./$(location :workflows) help \
+            --all_commands \
+            --header_level=1 \
+            --help_output_mode=markdown \
+            --prefix="$(location //:README.header.txt)" \
+            > "$@"
     """,
     tools = [":workflows"],
 )

mbo/app/commands.py

@@ -371,6 +371,12 @@ def __init__(self) -> None:
             type=Path,
             help="A file that should be used as a prefix on output.",
         )
+        self.parser.add_argument(
+            "--header_level",
+            default=0,
+            type=int,
+            help="The current header level which gets added to the generated headers.",
+        )
         self.esequential_mpty_lines: int = 0
 
     def Print(self, text: str = "") -> None:
@@ -407,17 +413,17 @@ def Print(self, text: str = "") -> None:
                 self.esequential_mpty_lines = 0
                 globals()["Print"](t)
 
-    def H1(self, text: str):
+    def _header(self, text: str, level: int = 1):
         if self.args.help_output_mode == HelpOutputMode.MARKDOWN:
-            self.Print(f"# {text.rstrip(':')}")
+            self.Print(f"{'#'*(level+self.args.header_level)} {text.rstrip(':')}")
         else:
             self.Print(f"{text}\n")
 
+    def H1(self, text: str):
+        self._header(text=text, level=1)
+
     def H2(self, text: str):
-        if self.args.help_output_mode == HelpOutputMode.MARKDOWN:
-            self.Print(f"## {text.rstrip(':')}")
-        else:
-            self.Print(f"{text}\n")
+        self._header(text=text, level=2)
 
     def Code(self, text: str):
         if self.args.help_output_mode == HelpOutputMode.MARKDOWN:

tools/readme_update.sh

@@ -2,4 +2,9 @@
 
 ROOT="$(realpath "$(dirname "${0}")/..")"
 
-bazel run //circleci:workflows --color=yes -- help --help_output_mode=markdown --all_commands --prefix="${ROOT}/README.header.txt" > "${ROOT}/README.md"
+bazel run //circleci:workflows --color=yes -- help \
+  --all_commands \
+  --header_level=1 \
+  --help_output_mode=markdown \
+  --prefix="${ROOT}/README.header.txt" \
+  > "${ROOT}/README.md"