argdown 0.0.1

Markdown export for the argparse module

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

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 ...]]

Arguments

Quick reference table

Short	Long	Default	Description
-h	--help		Show help
-			Read from STDIN
	--license		Print license
	--header	Arguments and Usage	Header text
	--usage-header	Usage	Header text
	--ref-header	Quick reference table	Header text
	--args-header	Arguments	Header text
-s	--spacey		Blank lines after headers
-r	--rst		Generate rst
-e	--hierarchy	#=-*+.	rst header order
-d	--hide-default		Hide default arg values
-t	--truncate-help		Truncate help in this table
	--header-depth	1	Header depth of top header
	--encoding	utf-8	Input file encoding
-f	--function	None	Function to call in file
-v	--version		Show version

-h, --help

show this help message and exit

-

Read from STDIN instead of a file.

--license

Print license information (MIT) and exit.

--header (Default: Arguments and Usage)

Header text for the Arguments and Usage section.

--usage-header (Default: Usage)

Header text for the Usage section.

--ref-header (Default: Quick reference table)

Header text for the Quick reference table section, a simple table of all the arguments.

--args-header (Default: Arguments)

Header text for the Arguments section, a detailed listing of all the arguments.

-s, --spacey

Output a blank line after headers.

-r, --rst

Generate rst (reStructured Text) instead of Markdown.

-e, --hierarchy (Default: #=-*+.)

Order of header characters to use for rst output.

-d, --hide-default

Don’t output default values for the arguments.

-t, --truncate-help

Truncate help in the Quick reference table section so that the table’s width doesn’t exceed –width. Makes terminal output prettier but means you’ll probably have to re-write help messages.

--header-depth (Default: 1)

Header depth; number of hashes to output before the top-level header.

--encoding (Default: utf-8)

Encoding of all input files. Frankly, there’s no excuse to ever use this argument

-f, --function (Default: None)

Function to be called to parse args. For example, if the arg-parsing mechanism is contained in a console() function (common if the script is a module and has a console entry point defined), enter –function console if console() must be called to define the argument parser.

-v, --version

show program’s version number and exit

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