doc/gendoc.py
author Yuya Nishihara <yuya@tcha.org>
Sat, 22 Oct 2016 14:35:10 +0900
changeset 30564 d83ca854fa21
parent 29397 844f72885fb9
child 32375 ff874d34c856
permissions -rwxr-xr-x
ui: factor out ui.load() to create a ui without loading configs (API) This allows us to write doctests depending on a ui object, but not on global configs. ui.load() is a class method so we can do wsgiui.load(). All ui() calls but for doctests are replaced with ui.load(). Some of them could be changed to not load configs later.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
27496
f22cd17a22e7 doc: add execute bit and fix shbang line for gendoc.py
timeless <timeless@mozdev.org>
parents: 27330
diff changeset
     1
#!/usr/bin/env python
19425
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     2
"""usage: %s DOC ...
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     3
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     4
where DOC is the name of a document
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     5
"""
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     6
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
     7
from __future__ import absolute_import
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
     8
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
     9
import os
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    10
import sys
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    11
import textwrap
27330
6fbf1159a85a doc: make gendoc.py module import policy aware
Gregory Szorc <gregory.szorc@gmail.com>
parents: 26413
diff changeset
    12
6fbf1159a85a doc: make gendoc.py module import policy aware
Gregory Szorc <gregory.szorc@gmail.com>
parents: 26413
diff changeset
    13
# This script is executed during installs and may not have C extensions
6fbf1159a85a doc: make gendoc.py module import policy aware
Gregory Szorc <gregory.szorc@gmail.com>
parents: 26413
diff changeset
    14
# available. Relax C module requirements.
6fbf1159a85a doc: make gendoc.py module import policy aware
Gregory Szorc <gregory.szorc@gmail.com>
parents: 26413
diff changeset
    15
os.environ['HGMODULEPOLICY'] = 'allow'
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    16
# import from the live mercurial repo
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    17
sys.path.insert(0, "..")
5209
bbdcdc7f170e gendoc: use demandimport
Matt Mackall <mpm@selenic.com>
parents: 3797
diff changeset
    18
from mercurial import demandimport; demandimport.enable()
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    19
from mercurial import (
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    20
    commands,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    21
    extensions,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    22
    help,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    23
    minirst,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    24
    ui as uimod,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    25
)
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    26
from mercurial.i18n import (
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    27
    gettext,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    28
    _,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    29
)
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    30
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    31
table = commands.table
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    32
globalopts = commands.globalopts
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    33
helptable = help.helptable
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    34
loaddoc = help.loaddoc
1814
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_desc(docstr):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    37
    if not docstr:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    38
        return "", ""
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    39
    # sanitize
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    40
    docstr = docstr.strip("\n")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    41
    docstr = docstr.rstrip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    42
    shortdesc = docstr.splitlines()[0].strip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    43
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    44
    i = docstr.find("\n")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    45
    if i != -1:
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 9792
diff changeset
    46
        desc = docstr[i + 2:]
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    47
    else:
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
    48
        desc = shortdesc
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
    49
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
    50
    desc = textwrap.dedent(desc)
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
    51
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    52
    return (shortdesc, desc)
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 get_opts(opts):
11321
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    55
    for opt in opts:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    56
        if len(opt) == 5:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    57
            shortopt, longopt, default, desc, optlabel = opt
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    58
        else:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    59
            shortopt, longopt, default, desc = opt
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
    60
            optlabel = _("VALUE")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    61
        allopts = []
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    62
        if shortopt:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    63
            allopts.append("-%s" % shortopt)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    64
        if longopt:
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    65
            allopts.append("--%s" % longopt)
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
    66
        if isinstance(default, list):
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
    67
            allopts[-1] += " <%s[+]>" % optlabel
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
    68
        elif (default is not None) and not isinstance(default, bool):
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
    69
            allopts[-1] += " <%s>" % optlabel
20655
37f3be9d1541 doc: gendoc.py creates valid output for option descriptions with newlines
Simon Heimberg <simohe@besonet.ch>
parents: 20081
diff changeset
    70
        if '\n' in desc:
37f3be9d1541 doc: gendoc.py creates valid output for option descriptions with newlines
Simon Heimberg <simohe@besonet.ch>
parents: 20081
diff changeset
    71
            # only remove line breaks and indentation
37f3be9d1541 doc: gendoc.py creates valid output for option descriptions with newlines
Simon Heimberg <simohe@besonet.ch>
parents: 20081
diff changeset
    72
            desc = ' '.join(l.lstrip() for l in desc.split('\n'))
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    73
        desc += default and _(" (default: %s)") % default or ""
13077
6b8d2ee24ce2 coding style: fix yield used as a function
Thomas Arendsen Hein <thomas@jtah.de>
parents: 12814
diff changeset
    74
        yield (", ".join(allopts), desc)
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    75
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
    76
def get_cmd(cmd, cmdtable):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    77
    d = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
    78
    attr = cmdtable[cmd]
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    79
    cmds = cmd.lstrip("^").split("|")
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    80
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    81
    d['cmd'] = cmds[0]
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    82
    d['aliases'] = cmd.split("|")[1:]
19231
814291b5e79c gendoc: make commnd __doc__ and extension __doc__ as translatable
Takumi IINO <trot.thunder@gmail.com>
parents: 18748
diff changeset
    83
    d['desc'] = get_desc(gettext(attr[0].__doc__))
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    84
    d['opts'] = list(get_opts(attr[1]))
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    85
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    86
    s = 'hg ' + cmds[0]
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    87
    if len(attr) > 2:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    88
        if not attr[2].startswith('hg'):
8546
a33d19dcf906 gendoc: add missing space in command synopsis
Ori Avtalion <ori@avtalion.name>
parents: 7376
diff changeset
    89
            s += ' ' + attr[2]
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    90
        else:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    91
            s = attr[2]
9622
9d1a480ca6ea gendoc: fix synopsis
Martin Geisler <mg@lazybytes.net>
parents: 9485
diff changeset
    92
    d['synopsis'] = s.strip()
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
    93
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    94
    return d
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    95
19423
5046fede7684 gendoc: rename to showdoc from show_doc
Takumi IINO <trot.thunder@gmail.com>
parents: 19322
diff changeset
    96
def showdoc(ui):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    97
    # print options
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17267
diff changeset
    98
    ui.write(minirst.section(_("Options")))
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
    99
    multioccur = False
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   100
    for optstr, desc in get_opts(globalopts):
12812
4d431a31a76e gendoc: re-add indentation to global option table
Martin Geisler <mg@lazybytes.net>
parents: 12804
diff changeset
   101
        ui.write("%s\n    %s\n\n" % (optstr, desc))
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   102
        if optstr.endswith("[+]>"):
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   103
            multioccur = True
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   104
    if multioccur:
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   105
        ui.write(_("\n[+] marked option can be specified multiple times\n"))
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   106
        ui.write("\n")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   107
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   108
    # print cmds
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17267
diff changeset
   109
    ui.write(minirst.section(_("Commands")))
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17267
diff changeset
   110
    commandprinter(ui, table, minirst.subsection)
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
   111
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   112
    # print help topics
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   113
    # The config help topic is included in the hgrc.5 man page.
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   114
    helpprinter(ui, helptable, minirst.section, exclude=['config'])
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
   115
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17267
diff changeset
   116
    ui.write(minirst.section(_("Extensions")))
16683
525fdb738975 cleanup: eradicate long lines
Brodie Rao <brodie@sf.io>
parents: 14943
diff changeset
   117
    ui.write(_("This section contains help for extensions that are "
525fdb738975 cleanup: eradicate long lines
Brodie Rao <brodie@sf.io>
parents: 14943
diff changeset
   118
               "distributed together with Mercurial. Help for other "
525fdb738975 cleanup: eradicate long lines
Brodie Rao <brodie@sf.io>
parents: 14943
diff changeset
   119
               "extensions is available in the help system."))
29397
844f72885fb9 check-code: detect "missing _() in ui message" more exactly
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 29090
diff changeset
   120
    ui.write(("\n\n"
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   121
             ".. contents::\n"
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   122
             "   :class: htmlonly\n"
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   123
             "   :local:\n"
29397
844f72885fb9 check-code: detect "missing _() in ui message" more exactly
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 29090
diff changeset
   124
             "   :depth: 1\n\n"))
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   125
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   126
    for extensionname in sorted(allextensionnames()):
27660
512f883c234c mercurial: pass ui to extensions.load (issue5007)
Jun Wu <quark@fb.com>
parents: 27496
diff changeset
   127
        mod = extensions.load(ui, extensionname, None)
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17267
diff changeset
   128
        ui.write(minirst.subsection(extensionname))
19231
814291b5e79c gendoc: make commnd __doc__ and extension __doc__ as translatable
Takumi IINO <trot.thunder@gmail.com>
parents: 18748
diff changeset
   129
        ui.write("%s\n\n" % gettext(mod.__doc__))
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   130
        cmdtable = getattr(mod, 'cmdtable', None)
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   131
        if cmdtable:
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17267
diff changeset
   132
            ui.write(minirst.subsubsection(_('Commands')))
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17267
diff changeset
   133
            commandprinter(ui, cmdtable, minirst.subsubsubsection)
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   134
19424
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   135
def showtopic(ui, topic):
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   136
    extrahelptable = [
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   137
        (["common"], '', loaddoc('common')),
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   138
        (["hg.1"], '', loaddoc('hg.1')),
29090
7b52cb384c38 hg-ssh: copy doc string to man page
Sean Farley <sean@farley.io>
parents: 28966
diff changeset
   139
        (["hg-ssh.8"], '', loaddoc('hg-ssh.8')),
19424
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   140
        (["hgignore.5"], '', loaddoc('hgignore.5')),
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   141
        (["hgrc.5"], '', loaddoc('hgrc.5')),
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   142
        (["hgignore.5.gendoc"], '', loaddoc('hgignore')),
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   143
        (["hgrc.5.gendoc"], '', loaddoc('config')),
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   144
    ]
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   145
    helpprinter(ui, helptable + extrahelptable, None, include=[topic])
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   146
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   147
def helpprinter(ui, helptable, sectionfunc, include=[], exclude=[]):
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   148
    for names, sec, doc in helptable:
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   149
        if exclude and names[0] in exclude:
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   150
            continue
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   151
        if include and names[0] not in include:
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   152
            continue
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   153
        for name in names:
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   154
            ui.write(".. _%s:\n" % name)
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   155
        ui.write("\n")
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   156
        if sectionfunc:
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   157
            ui.write(sectionfunc(sec))
21793
e0b29a0c36c4 gendoc: restore use of callable() since it was readded in Python 3.2
Augie Fackler <raf@durin42.com>
parents: 20689
diff changeset
   158
        if callable(doc):
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26412
diff changeset
   159
            doc = doc(ui)
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   160
        ui.write(doc)
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   161
        ui.write("\n")
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   162
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   163
def commandprinter(ui, cmdtable, sectionfunc):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   164
    h = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
   165
    for c, attr in cmdtable.items():
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   166
        f = c.split("|")[0]
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   167
        f = f.lstrip("^")
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   168
        h[f] = c
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   169
    cmds = h.keys()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   170
    cmds.sort()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   171
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   172
    for f in cmds:
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 9792
diff changeset
   173
        if f.startswith("debug"):
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 9792
diff changeset
   174
            continue
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
   175
        d = get_cmd(h[f], cmdtable)
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17267
diff changeset
   176
        ui.write(sectionfunc(d['cmd']))
20689
401f9b661a2d doc: show short description of each commands in generated documents
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 20655
diff changeset
   177
        # short description
401f9b661a2d doc: show short description of each commands in generated documents
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 20655
diff changeset
   178
        ui.write(d['desc'][0])
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   179
        # synopsis
12813
13fdef670c43 gendoc: support multi-line synopses
Martin Geisler <mg@lazybytes.net>
parents: 12812
diff changeset
   180
        ui.write("::\n\n")
13fdef670c43 gendoc: support multi-line synopses
Martin Geisler <mg@lazybytes.net>
parents: 12812
diff changeset
   181
        synopsislines = d['synopsis'].splitlines()
13fdef670c43 gendoc: support multi-line synopses
Martin Geisler <mg@lazybytes.net>
parents: 12812
diff changeset
   182
        for line in synopsislines:
13fdef670c43 gendoc: support multi-line synopses
Martin Geisler <mg@lazybytes.net>
parents: 12812
diff changeset
   183
            # some commands (such as rebase) have a multi-line
13fdef670c43 gendoc: support multi-line synopses
Martin Geisler <mg@lazybytes.net>
parents: 12812
diff changeset
   184
            # synopsis
12814
58bc5024805d gendoc: do not strip 'hg ' from synopsis
Martin Geisler <mg@lazybytes.net>
parents: 12813
diff changeset
   185
            ui.write("   %s\n" % line)
12813
13fdef670c43 gendoc: support multi-line synopses
Martin Geisler <mg@lazybytes.net>
parents: 12812
diff changeset
   186
        ui.write('\n')
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   187
        # description
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   188
        ui.write("%s\n\n" % d['desc'][1])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   189
        # options
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   190
        opt_output = list(d['opts'])
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   191
        if opt_output:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   192
            opts_len = max([len(line[0]) for line in opt_output])
13345
b8214d871338 doc: Capitalize the "options" header of mercurial commands
Javi Merino <cibervicho@gmail.com>
parents: 13077
diff changeset
   193
            ui.write(_("Options:\n\n"))
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   194
            multioccur = False
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   195
            for optstr, desc in opt_output:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   196
                if desc:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   197
                    s = "%-*s  %s" % (opts_len, optstr, desc)
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   198
                else:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   199
                    s = optstr
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
   200
                ui.write("%s\n" % s)
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   201
                if optstr.endswith("[+]>"):
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   202
                    multioccur = True
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   203
            if multioccur:
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   204
                ui.write(_("\n[+] marked option can be specified"
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   205
                           " multiple times\n"))
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   206
            ui.write("\n")
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   207
        # aliases
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   208
        if d['aliases']:
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   209
            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
   210
3797
54fd4d3b4fce Generate docs for help topics
Matt Mackall <mpm@selenic.com>
parents: 1814
diff changeset
   211
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   212
def allextensionnames():
14316
d5b525697ddb extensions: drop maxlength from enabled and disabled
Matt Mackall <mpm@selenic.com>
parents: 13345
diff changeset
   213
    return extensions.enabled().keys() + extensions.disabled().keys()
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   214
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   215
if __name__ == "__main__":
19425
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
   216
    doc = 'hg.1.gendoc'
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
   217
    if len(sys.argv) > 1:
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
   218
        doc = sys.argv[1]
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
   219
30564
d83ca854fa21 ui: factor out ui.load() to create a ui without loading configs (API)
Yuya Nishihara <yuya@tcha.org>
parents: 29397
diff changeset
   220
    ui = uimod.ui.load()
19425
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
   221
    if doc == 'hg.1.gendoc':
26412
7e8e3c0920a6 gendoc: use real ui in place of stdout
Yuya Nishihara <yuya@tcha.org>
parents: 21793
diff changeset
   222
        showdoc(ui)
19425
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
   223
    else:
26412
7e8e3c0920a6 gendoc: use real ui in place of stdout
Yuya Nishihara <yuya@tcha.org>
parents: 21793
diff changeset
   224
        showtopic(ui, sys.argv[1])