Skip to main content

Markdown export for the argparse module

Project description


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


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


Quick reference table







Show help


Read from STDIN


Print license


Arguments and Usage

Header text



Header text


Quick reference table

Header text



Header text



Blank lines after headers



Generate rst




rst header order



Hide default arg values



Truncate help in this table



Header depth of top header



Input file encoding




Function to call in file



Show version

-h, --help

show this help message and exit


Read from STDIN instead of a file.


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


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.


MIT, see license.txt

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

argdown-0.0.1-py3-none-any.whl (14.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page