about summary refs log tree commit diff
path: root/src
diff options
context:
space:
mode:
authorNguyễn Gia Phong <cnx@loang.net>2025-06-15 21:53:53 +0900
committerNguyễn Gia Phong <cnx@loang.net>2025-06-15 21:53:53 +0900
commitc3d356c8b80659468a0a7429636a128c156509ae (patch)
tree8d7af71b623e1cfb360ee935f809411059e0ca76 /src
parent637e73f023107c142c1eecc187c18a5581c10794 (diff)
downloadscadere-c3d356c8b80659468a0a7429636a128c156509ae.tar.gz
Add examples to help and man pages
Diffstat (limited to 'src')
-rw-r--r--src/scadere/__init__.py34
-rw-r--r--src/scadere/check.py21
-rw-r--r--src/scadere/listen.py34
3 files changed, 73 insertions, 16 deletions
diff --git a/src/scadere/__init__.py b/src/scadere/__init__.py
index ada0f29..f2b41bd 100644
--- a/src/scadere/__init__.py
+++ b/src/scadere/__init__.py
@@ -18,10 +18,15 @@
 
 from argparse import HelpFormatter, ONE_OR_MORE
 
-__all__ = ['__version__', 'GNUHelpFormatter', 'NetLoc']
+__all__ = ['__version__', 'GNUHelpFormatter', 'NetLoc', 'format_examples']
 __version__ = '0.1.0'
 
 
+EXAMPLE_PREFIX = ' ' * 2
+# help2man's implementation detail
+EXAMPLE_DESCRIPTION_PREFIX = ' ' * 20
+
+
 class GNUHelpFormatter(HelpFormatter):
     """Help formatter for ArgumentParser following GNU Coding Standards."""
 
@@ -33,6 +38,24 @@ class GNUHelpFormatter(HelpFormatter):
         """Substitute 'Options:' for 'options:'."""
         super().start_section(heading.capitalize())
 
+    def _fill_text(self, text, width, indent):
+        """Preserve examples' formatting."""
+        desc_position = max(len(EXAMPLE_DESCRIPTION_PREFIX),
+                            min(self._action_max_length+2,
+                                self._max_help_position))
+        desc_width = width - desc_position
+        desc_indent = indent + ' '*desc_position
+        example_indent = indent + EXAMPLE_PREFIX
+        parts = []
+        for line in text.splitlines():
+            if line.startswith(EXAMPLE_DESCRIPTION_PREFIX):
+                parts.append(super()._fill_text(line, desc_width, desc_indent))
+            elif line.startswith(EXAMPLE_PREFIX):
+                parts.append(example_indent+line.strip())
+            else:  # not example
+                parts.append(super()._fill_text(line, width, indent))
+        return '\n'.join(parts)
+
     def _format_args(self, action, default_metavar):
         """Substitute 'METAVAR...' for 'METAVAR [METAVAR ...]'."""
         if action.nargs == ONE_OR_MORE:
@@ -67,3 +90,12 @@ class NetLoc:
             return string, self.default_port
         hostname, port = string.rsplit(':', 1)
         return hostname, int(port)  # ValueError to be handled by argparse
+
+
+def format_examples(examples):
+    """Format example commands and their description ."""
+    lines = ['Examples:']
+    for example, description in examples:
+        lines.append(EXAMPLE_PREFIX+example)
+        lines.append(EXAMPLE_DESCRIPTION_PREFIX+description)
+    return '\n'.join(lines)
diff --git a/src/scadere/check.py b/src/scadere/check.py
index 0937e75..380f71c 100644
--- a/src/scadere/check.py
+++ b/src/scadere/check.py
@@ -27,7 +27,7 @@ from sys import argv, stderr, stdout
 from unicodedata import category as unicode_category
 from uuid import uuid4
 
-from . import __version__, GNUHelpFormatter, NetLoc
+from . import __version__, GNUHelpFormatter, NetLoc, format_examples
 
 __all__ = ['main']
 
@@ -94,12 +94,20 @@ def check(netlocs, after, output, fake_ca=None):
                       base64_from_str(ca), file=output)
 
 
-def main(arguments=argv[1:]):
+def main(prog='scadere-check', arguments=argv[1:]):
     """Run TLS checker."""
-    description = ('Check TLS certificate expiration of HOST,'
-                   ' where PORT defaults to 443.')
-    parser = ArgumentParser(prog='scadere-check', allow_abbrev=False,
-                            description=description,
+    desc = ('Check TLS certificate expiration of HOST,'
+            ' where PORT defaults to 443.\n\n'
+            'The output is intended to be used by scadere-listen(1).')
+    examples = [((f'{prog} --output=/var/lib/scadere/certificates'
+                  ' example.com example.net'),
+                 ('Check if TLS certificates used by example.com:443'
+                  ' and example.net:443 are either invalid'
+                  ' or expiring within the next week,'
+                  ' then write the result to /var/lib/scadere/certificates.'))]
+
+    parser = ArgumentParser(prog=prog, allow_abbrev=False, description=desc,
+                            epilog=format_examples(examples),
                             formatter_class=GNUHelpFormatter)
     parser.add_argument('-v', '--version', action='version',
                         version=f'%(prog)s {__version__}')
@@ -110,6 +118,7 @@ def main(arguments=argv[1:]):
     parser.add_argument('-o', '--output', metavar='PATH',
                         type=FileType('w'), default=stdout,
                         help='output file (default to stdout)')
+
     args = parser.parse_args(arguments)
     with args.output:  # pragma: no cover
         after = datetime.now(timezone.utc) + timedelta(days=args.days)
diff --git a/src/scadere/listen.py b/src/scadere/listen.py
index 649a7cd..2888524 100644
--- a/src/scadere/listen.py
+++ b/src/scadere/listen.py
@@ -32,7 +32,7 @@ from xml.etree.ElementTree import (Element as xml_element,
                                    indent, tostring as string_from_xml)
 from sys import argv
 
-from . import __version__, GNUHelpFormatter, NetLoc
+from . import __version__, GNUHelpFormatter, NetLoc, format_examples
 from .check import base64_from_str
 
 __all__ = ['main']
@@ -312,21 +312,37 @@ def with_trailing_slash(base_url):
     return base_url if base_url.endswith('/') else f'{base_url}/'
 
 
-def main(arguments=argv[1:]):
+def main(prog='scadere-listen', arguments=argv[1:]):
     """Launch server."""
-    description = ('Serve the TLS certificate expiration feed'
-                   ' from INPUT file for base URL at HOST:PORT,'
-                   ' where HOST defaults to localhost and PORT'
-                   ' is selected randomly if not specified.')
-    parser = ArgumentParser(prog='scadere-listen', allow_abbrev=False,
-                            description=description,
+    desc = ('Serve at URL Atom feeds for TLS certificate renewal reminder.'
+            '  It is possible for clients to filter domains'
+            ' using one or more "domain" URL queries.\n\n'
+            'The certificate information is read from the file at PATH,'
+            ' which is generated by scadere-check(1).\n\n'
+            'The server listens for TCP connections coming to HOST:PORT,'
+            ' where HOST defaults to localhost'
+            ' and PORT is selected randomly if not specified.\n\n')
+    examples = [((f'{prog} /var/lib/scadere/certificates'
+                  ' https://scadere.example/ :4433'),
+                 ('Serve renewal reminder feed using information'
+                  ' from /var/lib/scadere/certificates on localhost:4433,'
+                  ' to be reverse proxied to https://scadere.example/')),
+                ('https://scadere.example/',
+                 'Atom feed for all checked TLS certificates'),
+                ('https://scadere.example/?domain=example.com&domain=net',
+                 ('Atom feed for checked TLS certificates for example.com,'
+                  ' its subdomains, and domains under the TLD NET'))]
+
+    parser = ArgumentParser(prog=prog, allow_abbrev=False, description=desc,
+                            epilog=format_examples(examples),
                             formatter_class=GNUHelpFormatter)
     parser.add_argument('-v', '--version', action='version',
                         version=f'%(prog)s {__version__}')
-    parser.add_argument('certs', metavar='INPUT', type=Path)
+    parser.add_argument('certs', metavar='PATH', type=Path)
     parser.add_argument('base_url', metavar='URL', type=with_trailing_slash)
     parser.add_argument('netloc', metavar='[HOST][:PORT]', nargs='?',
                         type=NetLoc(None), default=('localhost', None))
+
     args = parser.parse_args(arguments)
     run(listen(args.certs, args.base_url, *args.netloc))  # pragma: no cover