help2rst

#!/usr/bin/env python3

# Copyright 2019 Regents of The University of Michigan.

# This file is part of geo-omics-scripts.

# Geo-omics-scripts is free software: you can redistribute it and/or
# modify it under the terms of the GNU General Public License as published
# by the Free Software Foundation, either version 3 of the License, or (at
# your option) any later version.

# Geo-omics-scripts is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.

# You should have received a copy of the GNU General Public License along
# with Geo-omics-scripts.  If not, see <https://www.gnu.org/licenses/>.

"""
Generate docs from programs help printout
"""

import argparse
from pathlib import Path
import re
import subprocess
from string import Template
import sys
from textwrap import wrap, indent


DEFAULT_TEMPLATE = 'docs/template.txt'

OPTION_TMPL = Template("""\
.. option:: $args

$help

""")


HELP_RE = (r'^usage: (?P<program>[-\w]+) (?P<usage_args>.*?)'
           r'\n\n(?P<description_1>*)$'
           r'\n\npositional arguments:\n(?P<positional_args>.*)'
           r'\n\noptional arguments:\n(?P<optional_args>.*?)'
           r'\n\n(?P<description_2>.*)')

OPTION_RE = r'^  (?P<args>[^\n]*?[^\s])(  +|\n)(?P<help>.*?)(?=(^  [^\s]|\Z))'


def parse_help(help_text):
    """
    Parse help and return dictionary of text elements
    """
    m = re.match(HELP_RE, help_text, re.MULTILINE | re.DOTALL)
    if m is None:
        raise RuntimeError('Failed to parse help text')

    return m.groupdict()


def fix_options(opt_section):
    ret = ''
    for m in re.finditer(OPTION_RE, opt_section, re.MULTILINE | re.DOTALL):
        sub = m.groupdict()
        # rm existing formatting:
        sub['help'] = re.sub(r' \s+', ' ', sub['help']).strip()
        sub['help'] = '\n'.join(wrap(sub['help']))
        sub['help'] = indent(sub['help'], '    ')

        ret += OPTION_TMPL.substitute(sub)

    ret = ret.rstrip()
    return ret


def main():
    argp = argparse.ArgumentParser(description=__doc__)
    argp.add_argument(
        'program',
        nargs='?',
        help='Path and name of the program.  If this is not given, then the '
             'program expects the help text to be provided via stdin.',
    )
    argp.add_argument(
        '-t', '--template',
        default=DEFAULT_TEMPLATE,
        help='Path to template file.',
    )
    args = argp.parse_args()

    if args.program is None:
        help_text = sys.stdin.read()
    else:
        prog = Path(args.program)
        if not prog.is_file():
            argp.error('Program file not found: {}'.format(prog))

        p = subprocess.run([str(prog), '-h'], stdout=subprocess.PIPE)
        help_text = p.stdout.decode()

    template = Path(args.template)
    if not template.is_file():
        argp.error('Template file not found: {}'.format(template))

    template = Template(template.read_text())

    # print(help_text)
    sub = parse_help(help_text)
    sub['usage_args'] = re.sub(r'\s+', ' ', sub['usage_args'])  # rm newlines
    sub['positional_args'] = fix_options(sub['positional_args'])
    sub['optional_args'] = fix_options(sub['optional_args'])
    sub['header_line'] = \
        '=' * (len(sub['program']) + 3 + len(sub['description_1']))
    print(template.substitute(**sub))


if __name__ == '__main__':
    main()