Package: argdown
argdownArgdown is an extension to Python’sargparsemodule 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 areadme.mdis
quite ugly. argdown is a python module that provides a functionargdown.md_help(parser)that accepts anArgumentParserobject and
returns a string of lovely help text.Argdown requires a fully formed ArgumentParser object, after all theadd_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 toargdown.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 toparse_argsis 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.argdownfile, as detailed in the.argdownsection..argdownA.argdownfile is a python literal and may be a list of preference-dicts
or a single preference-dict.Here’s an example.argdownpreference-dict with all possible values /
options filled in — any keys ommitted will default to these values (except foroptions, which defaults to the empty set — all options are shown here for
reference purposes).  Ifuse-stdinis present in theoptionskey, the
contents of thefileskey are discarded. No keys are mandatory, and an.argdownconsisting of an empty dict corresponds to the behavior of runningargdownfrom the command-line, with the exception of the command-line
invocation not executing all.pyfiles 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.argdownwill be parsed as Python code usingast.literal_eval, so feel free to use comments, raw strings, or other
Python niceties. Function calls won’t be executed, however.Arguments and UsageUsageusage: 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 ...]]ArgumentsQuick reference tableShortLongDefaultDescription-h--helpShow help-Read from STDIN--licensePrint license--headerArguments and UsageHeader text--usage-headerUsageHeader text--ref-headerQuick reference tableHeader text--args-headerArgumentsHeader text-s--spaceyBlank lines after headers-r--rstGenerate rst-e--hierarchy#=-*+.rst header order-d--hide-defaultHide default arg values-t--truncate-helpTruncate help in this table--header-depth1Header depth of top header--encodingutf-8Input file encoding-f--functionNoneFunction to call in file-v--versionShow version-h,--helpshow this help message and exit-Read from STDIN instead of a file.--licensePrint license information (MIT) and exit.--header(Default: Arguments and Usage)Header text for theArguments and Usagesection.--usage-header(Default: Usage)Header text for theUsagesection.--ref-header(Default: Quick reference table)Header text for theQuick reference tablesection, a simple table of all the
arguments.--args-header(Default: Arguments)Header text for theArgumentssection, a detailed listing of all the
arguments.-s,--spaceyOutput a blank line after headers.-r,--rstGenerate rst (reStructured Text) instead of Markdown.-e,--hierarchy(Default:#=-*+.)Order of header characters to use for rst output.-d,--hide-defaultDon’t output default values for the arguments.-t,--truncate-helpTruncate help in theQuick reference tablesection 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 aconsole()function (common if the script is a module and
has a console entry point defined), enter–function consoleifconsole()must be called to define the argument parser.-v,--versionshow program’s version number and exitToy test usageIf a filetest.pyreadsimport 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 runningargdown test.pyWill 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 Descriptionscheck for .short_descriptions filecheck for passed filenameif '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 bugsThere are no known bugs.Unknown bugsProbably a lot. This script was built to handle the subset ofargparse’s
features that I use, so I imagine there are areas in whichargdownperforms
poorly. Please open an issue if you find something.Missing featuresThe quick reference table output isn’t great; see above where theDefaultcolumn is included despite containing no content.Currently, withouttruncate_help=Falsepassed toargdown.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.LicenseMIT, seelicense.txt