cli yaml: implement auto documenter

[richardjgowers]

ideally we can generate example yaml files for the CLI from the CLI, that can then be customised then used

[richardjgowers]

import docstring_parser
from kartograf import KartografAtomMapper
import textwrap

def generate_doc_stub(thing):

    ds = docstring_parser.parse_from_object(thing.__init__)

    linewidth = 119

    print(f'# mapper: {thing.__name__}')
    print('#   settings:')

    prefix = '#     '
    linewidth -= len(prefix)
    comment = '# '

    for p in ds.params:
        if p.arg_name.startswith('_'):
            continue  # don't document private args
        if p.type_name not in {'float', 'int', 'string', 'bool'}:
            continue  # don't document arguments we can't handle

        desc = p.description
        arg_part = f'{p.arg_name}: {p.default} '

        desc_width = linewidth - len(arg_part) - len(comment)

        wrapped_desc = textwrap.wrap(p.description, width=desc_width)

        print(prefix + arg_part + comment + wrapped_desc[0])
        for l in wrapped_desc[1:]:
            print(prefix + ' ' * (linewidth - desc_width - len(comment)) + comment + l)

generate_doc_stub(KartografAtomMapper)

outputs:

# mapper: KartografAtomMapper
#   settings:
#     atom_max_distance: 0.95 # geometric criteria for two atoms, how far their
#                             # distance can be maximal (in Angstrom). Default
#                             # 0.95
#     map_hydrogens_on_hydrogens_only: False # map hydrogens only on hydrogens.
#                                            # Default False
#     map_exact_ring_matches_only: False # if true, only rings with matching
#                                        # ringsize and same bond-orders will
#                                        # be mapped. Additionally no ring-
#                                        # breaking is permitted. default False

where you could list multiple mappers and comment out the one that you are interested in?