Skip to content

cli: Prevent YAML wrapping in help displayed by Click

Antoine Lambert requested to merge anlambert/swh-scrubber:cli-doc-no-yaml-wrap into master

The default behavior of Click is to rewrap text based on the width of the terminal but as a consequence it makes the sample YAML config for the scrubber displayed in command help quite unreadable as indentation is lost.

So use \b markers in docstring to ensure proper display of the YAML config by Click.

Before:

$ swh -l DEBUG scrubber -C ~/.config/swh/objstorage_scrubber.yml -h
Usage: swh scrubber [OPTIONS] COMMAND [ARGS]...

  main command group of the datastore scrubber

  Expected config format::

      scrubber:         cls: postgresql         db: "service=..."    # libpq
      DSN

      # for storage checkers + origin locator only:     storage:         cls:
      postgresql     # cannot be remote for checkers, as they need direct
      # access to the pg DB         db": "service=..."  # libpq DSN
      objstorage:             cls: memory

      # for journal checkers only:     journal:         # see
      https://docs.softwareheritage.org/devel/apidoc/swh.journal.client.html
      # for the full list of options         sasl.mechanism: SCRAM-SHA-512
      security.protocol: SASL_SSL         sasl.username: ...
      sasl.password: ...         group_id: ...         privileged: True
      message.max.bytes: 524288000         brokers:           -
      "broker1.journal.softwareheritage.org:9093           -
      "broker2.journal.softwareheritage.org:9093           -
      "broker3.journal.softwareheritage.org:9093           -
      "broker4.journal.softwareheritage.org:9093           -
      "broker5.journal.softwareheritage.org:9093         object_types:
      [directory, revision, snapshot, release]         auto_offset_reset:
      earliest

Options:
  -C, --config-file FILE  Configuration file.
  -h, --help              Show this message and exit.

Commands:
  check   group of commands which read from data stores and report errors.
  fix     For each known corrupt object reported in the scrubber DB,...
  locate  For each known corrupt object reported in the scrubber DB,...

After:

$ swh -l DEBUG scrubber -C ~/.config/swh/objstorage_scrubber.yml -h
Usage: swh scrubber [OPTIONS] COMMAND [ARGS]...

  main command group of the datastore scrubber

  Expected config format::
      
      scrubber:
          cls: postgresql
          db: "service=..."    # libpq DSN
      
      # for storage checkers + origin locator only:
      storage:
          cls: postgresql     # cannot be remote for checkers, as they need direct
                              # access to the pg DB
          db": "service=..."  # libpq DSN
          objstorage:
              cls: memory
      
      # for journal checkers only:
      journal:
          # see https://docs.softwareheritage.org/devel/apidoc/swh.journal.client.html
          # for the full list of options
          sasl.mechanism: SCRAM-SHA-512
          security.protocol: SASL_SSL
          sasl.username: ...
          sasl.password: ...
          group_id: ...
          privileged: True
          message.max.bytes: 524288000
          brokers:
            - "broker1.journal.softwareheritage.org:9093
            - "broker2.journal.softwareheritage.org:9093
            - "broker3.journal.softwareheritage.org:9093
            - "broker4.journal.softwareheritage.org:9093
            - "broker5.journal.softwareheritage.org:9093
          object_types: [directory, revision, snapshot, release]
          auto_offset_reset: earliest

Options:
  -C, --config-file FILE  Configuration file.
  -h, --help              Show this message and exit.

Commands:
  check   group of commands which read from data stores and report errors.
  fix     For each known corrupt object reported in the scrubber DB,...
  locate  For each known corrupt object reported in the scrubber DB,...

Merge request reports