argdown 0.0.1

argdown

Argdown is an extension to Python’s argparse module that adds Markdown and RST documentation export.

The argparse module is great at generating command-line usage and help texts, but pasting pre-formatted and indented terminal output into a readme.md is quite ugly. argdown is a python module that provides a function argdown.md_help(parser) that accepts an ArgumentParser object and returns a string of lovely help text.

Argdown requires a fully formed ArgumentParser object, after all the add_argument() s have been executed. The only way to make sure the ArgumentParser object is created in the same way that it would be during normal script execution is to execute the script until the arguments are parsed. To do this, argdown reads the input file(s) until it reads a line containing .parse_args(. The rest of the file, being irrelevant to the command-line invocation, is truncated, and a call to argdown.md_help() is inserted to generate the Markdown from the parser. It is important to note that this means the whole script up until the call to parse_args is executed in its entirety, including any side-effects that may entail — argdown does not attempt to sanitize the code in any way.

There are two ways to use argdown — from the command-line, as detailed in the Arguments and Usage section, and for more persistent behavior, from a similar .argdown file, as detailed in the .argdown section.

.argdown

A .argdown file is a python literal and may be a list of preference-dicts or a single preference-dict.

Here’s an example .argdown preference-dict with all possible values / options filled in — any keys ommitted will default to these values (except for options, which defaults to the empty set — all options are shown here for reference purposes). If use-stdin is present in the options key, the contents of the files key are discarded. No keys are mandatory, and an .argdown consisting of an empty dict corresponds to the behavior of running argdown from the command-line, with the exception of the command-line invocation not executing all .py files in the current directory.

{
    'files': ['*.py'],
    'options': {
            'use-stdin', 'spacey', 'rst', 'hide-default', 'truncate-help'
    },
    'header':       'Arguments and Usage',
    'usage-header': 'Usage',
    'ref-header':   'Quick reference table',
    'args-header':  'Arguments',
    'hierarchy':    '#=-*+.',
    'header-depth': 1
    'encoding':     'utf-8',
    'function':     None
}

Any command-line arguments (see below) will override their corresponding values in all of a .argdown’s preference-dicts.

Note that the .argdown will be parsed as Python code using ast.literal_eval, so feel free to use comments, raw strings, or other Python niceties. Function calls won’t be executed, however.

Arguments and Usage

usage: argdown [-h] [-] [--license] [--header HEADER]
               [--usage-header USAGE_HEADER] [--ref-header REF_HEADER]
               [--args-header ARGS_HEADER] [-s] [-r] [-e HIERARCHY] [-d] [-t]
               [--header-depth HEADER_DEPTH] [--encoding ENCODING]
               [-f FUNCTION] [-v]
               [src_file [src_file ...]]

Toy test usage

If a file test.py reads

import argparse
import argdown

parser = argparse.ArgumentParser(description='Process some integers.')

parser.add_argument('integers', metavar='N', type=int, nargs='+',
help='an integer for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
const=sum, default=max,
help='sum the integers (default: find the max)')

args = parser.parse_args()

Then running

argdown test.py

Will output

# Arguments and Usage
## Usage
```
usage: argdown [-h] [--sum] N [N ...]
```

## Arguments
### Quick reference table
|Short|Long    |Default                |Description
|-----|--------|-----------------------|----------------------------------------
|`-h` |`--help`|                       |show this help message and exit
|     |`--sum` |<built-in function max>|sum the integers (default: find the max)

### `-h`, `--help`
show this help message and exit

### `--sum` (Default: <built-in function max>)
sum the integers (default: find the max)

Short Descriptions

1. check for .short_descriptions file

2. check for passed filename

if 'argdown' in globals():
    short_descriptions    = {
        '--help':          'Show help',
        '-':               'Read from STDIN',
        '--license':       'Print license',
        '--header':        'Header text',
        '--usage-header':  'Header text',
        '--ref-header':    'Header text',
        '--args-header':   'Header text',
        '--spacey':        'Blank lines after headers',
        '--rst':           'Generate rst',
        '--hierarchy':     'rst header order',
        '--hide-default':  'Hide default arg values',
        '--truncate-help': 'Truncate help in this table',
        '--header-depth':  'Header depth of top header',
        '--encoding':      'Input file encoding',
        '--function':      'Function to call in file',
        '--version':       'Show version',
    }

Known bugs

There are no known bugs.

Unknown bugs

Probably a lot. This script was built to handle the subset of argparse’s features that I use, so I imagine there are areas in which argdown performs poorly. Please open an issue if you find something.

Missing features

The quick reference table output isn’t great; see above where the Default column is included despite containing no content.

Currently, without truncate_help=False passed to argdown.md_help, the description field at the end of the table is truncated to the width of the terminal to prevent the table from looking awful. I’d like to add a feature to pass a dict of short descriptions to improve that in the future.

License

MIT, see license.txt