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