devscripts/make_readme.py

   1 #!/usr/bin/env python3
   2
   3 # yt-dlp --help | make_readme.py
   4 # This must be run in a console of correct width
   5 import functools
   6 import re
   7 import sys
   8
   9 README_FILE = 'README.md'
  10
  11 OPTIONS_START = 'General Options:'
  12 OPTIONS_END = 'CONFIGURATION'
  13 EPILOG_START = 'See full documentation'
  14 ALLOWED_OVERSHOOT = 2
  15
  16 DISABLE_PATCH = object()
  17
  18
  19 def take_section(text, start=None, end=None, *, shift=0):
  20     return text[
  21         text.index(start) + shift if start else None:
  22         text.index(end) + shift if end else None
  23     ]
  24
  25
  26 def apply_patch(text, patch):
  27     return text if patch[0] is DISABLE_PATCH else re.sub(*patch, text)
  28
  29
  30 options = take_section(sys.stdin.read(), f'\n  {OPTIONS_START}', f'\n{EPILOG_START}', shift=1)
  31
  32 max_width = max(map(len, options.split('\n')))
  33 switch_col_width = len(re.search(r'(?m)^\s{5,}', options).group())
  34 delim = f'\n{" " * switch_col_width}'
  35
  36 PATCHES = (
  37     (  # Headings
  38         r'(?m)^  (\w.+\n)(    (?=\w))?',
  39         r'## \1'
  40     ),
  41     (  # Do not split URLs
  42         rf'({delim[:-1]})? (?P<label>\[\S+\] )?(?P<url>https?({delim})?:({delim})?/({delim})?/(({delim})?\S+)+)\s',
  43         lambda mobj: ''.join((delim, mobj.group('label') or '', re.sub(r'\s+', '', mobj.group('url')), '\n'))
  44     ),
  45     (  # Do not split "words"
  46         rf'(?m)({delim}\S+)+$',
  47         lambda mobj: ''.join((delim, mobj.group(0).replace(delim, '')))
  48     ),
  49     (  # Allow overshooting last line
  50         rf'(?m)^(?P<prev>.+)${delim}(?P<current>.+)$(?!{delim})',
  51         lambda mobj: (mobj.group().replace(delim, ' ')
  52                       if len(mobj.group()) - len(delim) + 1 <= max_width + ALLOWED_OVERSHOOT
  53                       else mobj.group())
  54     ),
  55     (  # Avoid newline when a space is available b/w switch and description
  56         DISABLE_PATCH,  # This creates issues with prepare_manpage
  57         r'(?m)^(\s{4}-.{%d})(%s)' % (switch_col_width - 6, delim),
  58         r'\1 '
  59     ),
  60 )
  61
  62 with open(README_FILE, encoding='utf-8') as f:
  63     readme = f.read()
  64
  65 with open(README_FILE, 'w', encoding='utf-8') as f:
  66     f.write(''.join((
  67         take_section(readme, end=f'## {OPTIONS_START}'),
  68         functools.reduce(apply_patch, PATCHES, options),
  69         take_section(readme, f'# {OPTIONS_END}'),
  70     )))