doc/gendoc.py
author Martin Geisler <mg@lazybytes.net>
Thu, 16 Jul 2009 23:25:26 +0200
changeset 9158 d6eecafaf12f
parent 9130 335f749cc369
child 9241 d98cef25b5af
permissions -rw-r--r--
doc: use reStructuredText for man and HTML pages The Makefile now requires the rst2html and rst2man programs. Both can be found in Debian testing or downloaded from the Docutils homepage: http://docutils.sf.net/ http://docutils.sf.net/sandbox/manpage-writer/ The new HTML and man pages no longer contain huge amounts of un-wrapping literal blocks, thanks to how snippets of reStructuredText can easily be included inside other reStructuredText documents. The HTML pages now have anchors for all sections, including the help topics in hgrc.1 which were missing from the old HTML pages.
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):
9158
d6eecafaf12f doc: use reStructuredText for man and HTML pages
Martin Geisler <mg@lazybytes.net>
parents: 9130
diff changeset
    65
        ui.write("%s\n    %s\n\n" % (optstr, desc))
1814
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
9158
d6eecafaf12f doc: use reStructuredText for man and HTML pages
Martin Geisler <mg@lazybytes.net>
parents: 9130
diff changeset
    81
        ui.write(".. _%s:\n\n" % d['cmd'])
d6eecafaf12f doc: use reStructuredText for man and HTML pages
Martin Geisler <mg@lazybytes.net>
parents: 9130
diff changeset
    82
        ui.write("``%s``\n" % d['synopsis'].replace("hg ","", 1))
6488
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])
9158
d6eecafaf12f doc: use reStructuredText for man and HTML pages
Martin Geisler <mg@lazybytes.net>
parents: 9130
diff changeset
    89
            ui.write(_("    options:\n\n"))
6488
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)