doc/gendoc.py
author Matt Mackall <mpm@selenic.com>
Fri, 14 Nov 2008 14:12:16 -0600
changeset 7376 fc06bd17c985
parent 7014 46456a51e247
child 8546 a33d19dcf906
permissions -rw-r--r--
doc: handle shortened command synopses
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
     1
import sys, textwrap
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
     2
# import from the live mercurial repo
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
     3
sys.path.insert(0, "..")
5209
bbdcdc7f170e gendoc: use demandimport
Matt Mackall <mpm@selenic.com>
parents: 3797
diff changeset
     4
from mercurial import demandimport; demandimport.enable()
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
     5
from mercurial.commands import table, globalopts
7014
46456a51e247 i18n: use gettext instead of _
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
     6
from mercurial.i18n import gettext, _
3797
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
     7
from mercurial.help import helptable
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
     8
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
     9
def get_desc(docstr):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    10
    if not docstr:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    11
        return "", ""
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    12
    # sanitize
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    13
    docstr = docstr.strip("\n")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    14
    docstr = docstr.rstrip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    15
    shortdesc = docstr.splitlines()[0].strip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    16
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    17
    i = docstr.find("\n")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    18
    if i != -1:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    19
        desc = docstr[i+2:]
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    20
    else:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    21
        desc = "    %s" % shortdesc
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    22
    return (shortdesc, desc)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    23
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    24
def get_opts(opts):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    25
    for shortopt, longopt, default, desc in opts:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    26
        allopts = []
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    27
        if shortopt:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    28
            allopts.append("-%s" % shortopt)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    29
        if longopt:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    30
            allopts.append("--%s" % longopt)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    31
        desc += default and _(" (default: %s)") % default or ""
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    32
        yield(", ".join(allopts), desc)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    33
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    34
def get_cmd(cmd):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    35
    d = {}
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    36
    attr = table[cmd]
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    37
    cmds = cmd.lstrip("^").split("|")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    38
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    39
    d['cmd'] = cmds[0]
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    40
    d['aliases'] = cmd.split("|")[1:]
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    41
    d['desc'] = get_desc(attr[0].__doc__)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    42
    d['opts'] = list(get_opts(attr[1]))
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    43
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    44
    s = 'hg ' + cmds[0]
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    45
    if len(attr) > 2:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    46
        if not attr[2].startswith('hg'):
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    47
            s += attr[2]
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    48
        else:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    49
            s = attr[2]
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    50
    d['synopsis'] = s
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    51
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    52
    return d
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    53
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    54
def show_doc(ui):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    55
    def bold(s, text=""):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    56
        ui.write("%s\n%s\n%s\n" % (s, "="*len(s), text))
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    57
    def underlined(s, text=""):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    58
        ui.write("%s\n%s\n%s\n" % (s, "-"*len(s), text))
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    59
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    60
    # print options
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    61
    underlined(_("OPTIONS"))
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    62
    for optstr, desc in get_opts(globalopts):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    63
        ui.write("%s::\n    %s\n\n" % (optstr, desc))
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    64
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    65
    # print cmds
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    66
    underlined(_("COMMANDS"))
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    67
    h = {}
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    68
    for c, attr in table.items():
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    69
        f = c.split("|")[0]
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    70
        f = f.lstrip("^")
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    71
        h[f] = c
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    72
    cmds = h.keys()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    73
    cmds.sort()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    74
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    75
    for f in cmds:
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    76
        if f.startswith("debug"): continue
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    77
        d = get_cmd(h[f])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    78
        # synopsis
6612
59e087f99920 gendoc: add anchors for commands
Adrian Buehlmann <adrian@cadifra.com>
parents: 6488
diff changeset
    79
        ui.write("[[%s]]\n" % d['cmd'])
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    80
        ui.write("%s::\n" % d['synopsis'].replace("hg ","", 1))
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    81
        # description
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    82
        ui.write("%s\n\n" % d['desc'][1])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    83
        # options
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    84
        opt_output = list(d['opts'])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    85
        if opt_output:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    86
            opts_len = max([len(line[0]) for line in opt_output])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    87
            ui.write(_("    options:\n"))
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    88
            for optstr, desc in opt_output:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    89
                if desc:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    90
                    s = "%-*s  %s" % (opts_len, optstr, desc)
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    91
                else:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    92
                    s = optstr
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    93
                s = textwrap.fill(s, initial_indent=4 * " ",
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    94
                                  subsequent_indent=(6 + opts_len) * " ")
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    95
                ui.write("%s\n" % s)
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    96
            ui.write("\n")
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    97
        # aliases
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    98
        if d['aliases']:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
    99
            ui.write(_("    aliases: %s\n\n") % " ".join(d['aliases']))
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   100
3797
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
   101
    # print topics
7012
78341ea65d16 restructure helptable
Martin Geisler <mg@daimi.au.dk>
parents: 6654
diff changeset
   102
    for names, section, doc in helptable:
7014
46456a51e247 i18n: use gettext instead of _
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
   103
        underlined(gettext(section).upper())
3797
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
   104
        if callable(doc):
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
   105
            doc = doc()
7014
46456a51e247 i18n: use gettext instead of _
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
   106
        ui.write(gettext(doc))
3797
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
   107
        ui.write("\n")
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
   108
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   109
if __name__ == "__main__":
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   110
    show_doc(sys.stdout)