mercurial/help.py
author Yuya Nishihara <yuya@tcha.org>
Sat, 15 Sep 2018 12:34:13 +0900
changeset 39752 2d478b05fb14
parent 39614 a2880ac67ee0
child 40263 8cf459d8b111
permissions -rw-r--r--
bookmarks: reject --delete with --inactive which makes no sense A deleted bookmark is neither active nor inactive.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
3795
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     1
# help.py - help data for mercurial
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     2
#
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     3
# Copyright 2006 Matt Mackall <mpm@selenic.com>
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     4
#
8225
46293a0c7e9f updated license to be explicit about GPL version 2
Martin Geisler <mg@lazybytes.net>
parents: 8159
diff changeset
     5
# This software may be used and distributed according to the terms of the
10263
25e572394f5c Update license to GPLv2+
Matt Mackall <mpm@selenic.com>
parents: 9785
diff changeset
     6
# GNU General Public License version 2 or any later version.
3795
17a11f4ff260 Add basic support for help topics and a dates topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
     7
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
     8
from __future__ import absolute_import
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
     9
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    10
import itertools
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    11
import os
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    12
import textwrap
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    13
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    14
from .i18n import (
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    15
    _,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    16
    gettext,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    17
)
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    18
from . import (
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    19
    cmdutil,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    20
    encoding,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    21
    error,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    22
    extensions,
37091
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
    23
    fancyopts,
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    24
    filemerge,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    25
    fileset,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    26
    minirst,
32143
964c6be36590 py3: make sure opts are passed and used correctly in help command
Pulkit Goyal <7895pulkit@gmail.com>
parents: 32076
diff changeset
    27
    pycompat,
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    28
    revset,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    29
    templatefilters,
36922
521f6c7e1756 templater: split template functions to new module
Yuya Nishihara <yuya@tcha.org>
parents: 36451
diff changeset
    30
    templatefuncs,
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    31
    templatekw,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    32
    util,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    33
)
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    34
from .hgweb import (
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    35
    webcommands,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    36
)
8863
7b19c3c0172b help: adding a new help topic about extensions
Cédric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
    37
32291
bd872f64a8ba cleanup: use set literals
Martin von Zweigbergk <martinvonz@google.com>
parents: 32143
diff changeset
    38
_exclkeywords = {
31080
6918c9215201 help: hide command line options marked as "advanced"
Jun Wu <quark@fb.com>
parents: 31061
diff changeset
    39
    "(ADVANCED)",
26370
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    40
    "(DEPRECATED)",
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    41
    "(EXPERIMENTAL)",
31080
6918c9215201 help: hide command line options marked as "advanced"
Jun Wu <quark@fb.com>
parents: 31061
diff changeset
    42
    # i18n: "(ADVANCED)" is a keyword, must be translated consistently
6918c9215201 help: hide command line options marked as "advanced"
Jun Wu <quark@fb.com>
parents: 31061
diff changeset
    43
    _("(ADVANCED)"),
26370
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    44
    # i18n: "(DEPRECATED)" is a keyword, must be translated consistently
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    45
    _("(DEPRECATED)"),
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    46
    # i18n: "(EXPERIMENTAL)" is a keyword, must be translated consistently
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    47
    _("(EXPERIMENTAL)"),
32291
bd872f64a8ba cleanup: use set literals
Martin von Zweigbergk <martinvonz@google.com>
parents: 32143
diff changeset
    48
}
26369
4799b5c4aaf4 help: define list of keywords that should be excluded from non-verbose output
Yuya Nishihara <yuya@tcha.org>
parents: 26238
diff changeset
    49
20582
02c303f64917 help: exclude deprecated extensions in the disabled part of 'help extensions'
Augie Fackler <raf@durin42.com>
parents: 20034
diff changeset
    50
def listexts(header, exts, indent=1, showdeprecated=False):
8879
d0a3eadfbdb3 help: more improvements for the extensions topic
Cédric Duval <cedricduval@free.fr>
parents: 8871
diff changeset
    51
    '''return a text listing of the given extensions'''
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
    52
    rst = []
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
    53
    if exts:
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
    54
        for name, desc in sorted(exts.iteritems()):
26371
51b309ce6c7d help: unify handling of DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26370
diff changeset
    55
            if not showdeprecated and any(w in desc for w in _exclkeywords):
20582
02c303f64917 help: exclude deprecated extensions in the disabled part of 'help extensions'
Augie Fackler <raf@durin42.com>
parents: 20034
diff changeset
    56
                continue
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
    57
            rst.append('%s:%s: %s\n' % (' ' * indent, name, desc))
27151
7625f6387fc4 help: make listexts less confusing for deprecated exts
timeless <timeless@mozdev.org>
parents: 26845
diff changeset
    58
    if rst:
7625f6387fc4 help: make listexts less confusing for deprecated exts
timeless <timeless@mozdev.org>
parents: 26845
diff changeset
    59
        rst.insert(0, '\n%s\n\n' % header)
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
    60
    return rst
8864
cad6370a15cb help: refactor extensions listing, and show enabled ones in the dedicated topic
Cédric Duval <cedricduval@free.fr>
parents: 8863
diff changeset
    61
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
    62
def extshelp(ui):
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
    63
    rst = loaddoc('extensions')(ui).splitlines(True)
20582
02c303f64917 help: exclude deprecated extensions in the disabled part of 'help extensions'
Augie Fackler <raf@durin42.com>
parents: 20034
diff changeset
    64
    rst.extend(listexts(
02c303f64917 help: exclude deprecated extensions in the disabled part of 'help extensions'
Augie Fackler <raf@durin42.com>
parents: 20034
diff changeset
    65
        _('enabled extensions:'), extensions.enabled(), showdeprecated=True))
36249
c792f7c64f0c help: list deprecated and experimental extensions if --verbose
Yuya Nishihara <yuya@tcha.org>
parents: 35356
diff changeset
    66
    rst.extend(listexts(_('disabled extensions:'), extensions.disabled(),
c792f7c64f0c help: list deprecated and experimental extensions if --verbose
Yuya Nishihara <yuya@tcha.org>
parents: 35356
diff changeset
    67
                        showdeprecated=ui.verbose))
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
    68
    doc = ''.join(rst)
8863
7b19c3c0172b help: adding a new help topic about extensions
Cédric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
    69
    return doc
7013
f56e788fa292 i18n: mark help strings for translation
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
    70
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
    71
def optrst(header, options, verbose):
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    72
    data = []
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    73
    multioccur = False
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    74
    for option in options:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    75
        if len(option) == 5:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    76
            shortopt, longopt, default, desc, optlabel = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    77
        else:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    78
            shortopt, longopt, default, desc = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    79
            optlabel = _("VALUE") # default label
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    80
26369
4799b5c4aaf4 help: define list of keywords that should be excluded from non-verbose output
Yuya Nishihara <yuya@tcha.org>
parents: 26238
diff changeset
    81
        if not verbose and any(w in desc for w in _exclkeywords):
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    82
            continue
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    83
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    84
        so = ''
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    85
        if shortopt:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    86
            so = '-' + shortopt
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    87
        lo = '--' + longopt
37091
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
    88
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
    89
        if isinstance(default, fancyopts.customopt):
37092
ef6215df2402 fancyopts: prevent mutation of the default value in customopts
Daniel Ploch <dploch@google.com>
parents: 37091
diff changeset
    90
            default = default.getdefaultvalue()
37091
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
    91
        if default and not callable(default):
32619
d110fb58424c help: convert flag default to bytes portably
Augie Fackler <raf@durin42.com>
parents: 32615
diff changeset
    92
            # default is of unknown type, and in Python 2 we abused
d110fb58424c help: convert flag default to bytes portably
Augie Fackler <raf@durin42.com>
parents: 32615
diff changeset
    93
            # the %s-shows-repr property to handle integers etc. To
d110fb58424c help: convert flag default to bytes portably
Augie Fackler <raf@durin42.com>
parents: 32615
diff changeset
    94
            # match that behavior on Python 3, we do str(default) and
d110fb58424c help: convert flag default to bytes portably
Augie Fackler <raf@durin42.com>
parents: 32615
diff changeset
    95
            # then convert it to bytes.
d110fb58424c help: convert flag default to bytes portably
Augie Fackler <raf@durin42.com>
parents: 32615
diff changeset
    96
            desc += _(" (default: %s)") % pycompat.bytestr(default)
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    97
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    98
        if isinstance(default, list):
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
    99
            lo += " %s [+]" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   100
            multioccur = True
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   101
        elif (default is not None) and not isinstance(default, bool):
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   102
            lo += " %s" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   103
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   104
        data.append((so, lo, desc))
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   105
22117
c1d93edcf004 help: fold repeatable option message into option table header
Matt Mackall <mpm@selenic.com>
parents: 22116
diff changeset
   106
    if multioccur:
c1d93edcf004 help: fold repeatable option message into option table header
Matt Mackall <mpm@selenic.com>
parents: 22116
diff changeset
   107
        header += (_(" ([+] can be repeated)"))
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   108
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   109
    rst = ['\n%s:\n\n' % header]
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   110
    rst.extend(minirst.maketable(data, 1))
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   111
16815
e740746ea557 minirst: generate tables as a list of joined lines
Olav Reinert <seroton10@gmail.com>
parents: 16781
diff changeset
   112
    return ''.join(rst)
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   113
17837
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
   114
def indicateomitted(rst, omitted, notomitted=None):
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
   115
    rst.append('\n\n.. container:: omitted\n\n    %s\n\n' % omitted)
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
   116
    if notomitted:
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
   117
        rst.append('\n\n.. container:: notomitted\n\n    %s\n\n' % notomitted)
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
   118
27323
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   119
def filtercmd(ui, cmd, kw, doc):
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   120
    if not ui.debugflag and cmd.startswith("debug") and kw != "debug":
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   121
        return True
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   122
    if not ui.verbose and doc and any(w in doc for w in _exclkeywords):
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   123
        return True
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   124
    return False
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   125
32566
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   126
def topicmatch(ui, commands, kw):
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   127
    """Return help topics matching kw.
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   128
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   129
    Returns {'section': [(name, summary), ...], ...} where section is
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   130
    one of topics, commands, extensions, or extensioncommands.
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   131
    """
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   132
    kw = encoding.lower(kw)
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   133
    def lowercontains(container):
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   134
        return kw in encoding.lower(container)  # translated in helptable
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   135
    results = {'topics': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   136
               'commands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   137
               'extensions': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   138
               'extensioncommands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   139
               }
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   140
    for names, header, doc in helptable:
22322
e284de138f00 help: only call doc() when it is callable
Gregory Szorc <gregory.szorc@gmail.com>
parents: 21796
diff changeset
   141
        # Old extensions may use a str as doc.
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   142
        if (sum(map(lowercontains, names))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   143
            or lowercontains(header)
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   144
            or (callable(doc) and lowercontains(doc(ui)))):
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   145
            results['topics'].append((names[0], header))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   146
    for cmd, entry in commands.table.iteritems():
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   147
        if len(entry) == 3:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   148
            summary = entry[2]
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   149
        else:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   150
            summary = ''
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   151
        # translate docs *before* searching there
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   152
        docs = _(pycompat.getdoc(entry[0])) or ''
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   153
        if kw in cmd or lowercontains(summary) or lowercontains(docs):
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   154
            doclines = docs.splitlines()
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   155
            if doclines:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   156
                summary = doclines[0]
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   157
            cmdname = cmdutil.parsealiases(cmd)[0]
27324
5456374561a7 help: call filtercmd from topicmatch
timeless <timeless@mozdev.org>
parents: 27323
diff changeset
   158
            if filtercmd(ui, cmdname, kw, docs):
5456374561a7 help: call filtercmd from topicmatch
timeless <timeless@mozdev.org>
parents: 27323
diff changeset
   159
                continue
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   160
            results['commands'].append((cmdname, summary))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   161
    for name, docs in itertools.chain(
19769
83d79a00cc24 help: use full name of extensions to look up them for keyword search
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 18748
diff changeset
   162
        extensions.enabled(False).iteritems(),
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   163
        extensions.disabled().iteritems()):
28058
ff6e8dc659f8 help: don't crash in keyword search if an extension fails to provide docs
Simon Farnsworth <simonfar@fb.com>
parents: 27660
diff changeset
   164
        if not docs:
ff6e8dc659f8 help: don't crash in keyword search if an extension fails to provide docs
Simon Farnsworth <simonfar@fb.com>
parents: 27660
diff changeset
   165
            continue
26845
7a77ee434179 help: replace some str.split() calls by str.partition() or str.rpartition()
Anton Shestakov <av6@dwimlabs.net>
parents: 26587
diff changeset
   166
        name = name.rpartition('.')[-1]
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   167
        if lowercontains(name) or lowercontains(docs):
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   168
            # extension docs are already translated
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   169
            results['extensions'].append((name, docs.splitlines()[0]))
34912
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   170
        try:
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   171
            mod = extensions.load(ui, name, '')
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   172
        except ImportError:
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   173
            # debug message would be printed in extensions.load()
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   174
            continue
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   175
        for cmd, entry in getattr(mod, 'cmdtable', {}).iteritems():
16711
497deec204d1 help: add --keyword (-k) for searching help
Augie Fackler <raf@durin42.com>
parents: 16710
diff changeset
   176
            if kw in cmd or (len(entry) > 2 and lowercontains(entry[2])):
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   177
                cmdname = cmdutil.parsealiases(cmd)[0]
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   178
                cmddoc = pycompat.getdoc(entry[0])
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   179
                if cmddoc:
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   180
                    cmddoc = gettext(cmddoc).splitlines()[0]
16884
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
   181
                else:
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
   182
                    cmddoc = _('(no help text available)')
27387
dfab0afde928 help: filter extension commands
timeless <timeless@mozdev.org>
parents: 27379
diff changeset
   183
                if filtercmd(ui, cmdname, kw, cmddoc):
dfab0afde928 help: filter extension commands
timeless <timeless@mozdev.org>
parents: 27379
diff changeset
   184
                    continue
16884
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
   185
                results['extensioncommands'].append((cmdname, cmddoc))
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   186
    return results
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   187
27375
c4a062d090ee help: teach loaddoc to load from a different directory
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27325
diff changeset
   188
def loaddoc(topic, subdir=None):
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   189
    """Return a delayed loader for help/topic.txt."""
3798
6f0c42d50394 move environment topic
Matt Mackall <mpm@selenic.com>
parents: 3795
diff changeset
   190
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   191
    def loader(ui):
22637
149141c3a25f help: don't search randomly for help data - trust util.datapath
Mads Kiilerich <madski@unity3d.com>
parents: 22633
diff changeset
   192
        docdir = os.path.join(util.datapath, 'help')
27375
c4a062d090ee help: teach loaddoc to load from a different directory
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27325
diff changeset
   193
        if subdir:
c4a062d090ee help: teach loaddoc to load from a different directory
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27325
diff changeset
   194
            docdir = os.path.join(docdir, subdir)
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   195
        path = os.path.join(docdir, topic + ".txt")
14168
135e244776f0 prevent transient leaks of file handle by using new helper functions
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 14044
diff changeset
   196
        doc = gettext(util.readfile(path))
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   197
        for rewriter in helphooks.get(topic, []):
26414
c44b507e7c78 help: pass around ui to rewriter hooks (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26413
diff changeset
   198
            doc = rewriter(ui, topic, doc)
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   199
        return doc
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   200
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   201
    return loader
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
   202
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   203
internalstable = sorted([
36451
1fa35ca345a5 internals: document bundle2 format
Gregory Szorc <gregory.szorc@gmail.com>
parents: 36250
diff changeset
   204
    (['bundle2'], _('Bundle2'),
1fa35ca345a5 internals: document bundle2 format
Gregory Szorc <gregory.szorc@gmail.com>
parents: 36250
diff changeset
   205
     loaddoc('bundle2', subdir='internals')),
29747
aba2bb2a6d0f help: don't try to render a section on sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 28828
diff changeset
   206
    (['bundles'], _('Bundles'),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   207
     loaddoc('bundles', subdir='internals')),
39409
2fe21c65777e internals: document CBOR utilization
Gregory Szorc <gregory.szorc@gmail.com>
parents: 39339
diff changeset
   208
    (['cbor'], _('CBOR'),
2fe21c65777e internals: document CBOR utilization
Gregory Szorc <gregory.szorc@gmail.com>
parents: 39339
diff changeset
   209
     loaddoc('cbor', subdir='internals')),
31293
2cdb1239ff8c help: update help.internalstable for new censor docs
Augie Fackler <augie@google.com>
parents: 31265
diff changeset
   210
    (['censor'], _('Censor'),
2cdb1239ff8c help: update help.internalstable for new censor docs
Augie Fackler <augie@google.com>
parents: 31265
diff changeset
   211
     loaddoc('censor', subdir='internals')),
29747
aba2bb2a6d0f help: don't try to render a section on sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 28828
diff changeset
   212
    (['changegroups'], _('Changegroups'),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   213
     loaddoc('changegroups', subdir='internals')),
34951
fb7f58daca48 internals: copy-edit "register" -> "registrar" in configitem docs
Kevin Bullock <kbullock+mercurial@ringworld.org>
parents: 34932
diff changeset
   214
    (['config'], _('Config Registrar'),
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents: 34912
diff changeset
   215
     loaddoc('config', subdir='internals')),
29747
aba2bb2a6d0f help: don't try to render a section on sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 28828
diff changeset
   216
    (['requirements'], _('Repository Requirements'),
28523
045fe7042510 help: document requirements
Gregory Szorc <gregory.szorc@gmail.com>
parents: 28058
diff changeset
   217
     loaddoc('requirements', subdir='internals')),
29747
aba2bb2a6d0f help: don't try to render a section on sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 28828
diff changeset
   218
    (['revlogs'], _('Revision Logs'),
27631
c18292a6ff54 internals: document revlog format
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27479
diff changeset
   219
     loaddoc('revlogs', subdir='internals')),
29859
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29747
diff changeset
   220
    (['wireprotocol'], _('Wire Protocol'),
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29747
diff changeset
   221
     loaddoc('wireprotocol', subdir='internals')),
39614
a2880ac67ee0 help: add internals.wireprotocolrpc to the table
Yuya Nishihara <yuya@tcha.org>
parents: 39461
diff changeset
   222
    (['wireprotocolrpc'], _('Wire Protocol RPC'),
a2880ac67ee0 help: add internals.wireprotocolrpc to the table
Yuya Nishihara <yuya@tcha.org>
parents: 39461
diff changeset
   223
     loaddoc('wireprotocolrpc', subdir='internals')),
39461
7df9ae38c75c help: add internals.wireprotocolv2 to the table, and remove redundant header
Yuya Nishihara <yuya@tcha.org>
parents: 39409
diff changeset
   224
    (['wireprotocolv2'], _('Wire Protocol Version 2'),
7df9ae38c75c help: add internals.wireprotocolv2 to the table, and remove redundant header
Yuya Nishihara <yuya@tcha.org>
parents: 39409
diff changeset
   225
     loaddoc('wireprotocolv2', subdir='internals')),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   226
])
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   227
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   228
def internalshelp(ui):
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   229
    """Generate the index for the "internals" topic."""
32076
d7b698ae153b help: explain how to access subtopics in internals
Matt DeVore <matvore@google.com>
parents: 31793
diff changeset
   230
    lines = ['To access a subtopic, use "hg help internals.{subtopic-name}"\n',
d7b698ae153b help: explain how to access subtopics in internals
Matt DeVore <matvore@google.com>
parents: 31793
diff changeset
   231
             '\n']
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   232
    for names, header, doc in internalstable:
27400
64208bd4c580 help: add missed last new line to "internals" topic
Yuya Nishihara <yuya@tcha.org>
parents: 27387
diff changeset
   233
        lines.append(' :%s: %s\n' % (names[0], header))
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   234
27400
64208bd4c580 help: add missed last new line to "internals" topic
Yuya Nishihara <yuya@tcha.org>
parents: 27387
diff changeset
   235
    return ''.join(lines)
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   236
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
   237
helptable = sorted([
31793
69d8fcf20014 help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents: 31293
diff changeset
   238
    (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')),
31129
71f692f1f678 color: update the help table
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 31080
diff changeset
   239
    (['color'], _("Colorizing Outputs"), loaddoc('color')),
12145
c407b4ca666e help: make "hg help hgrc" an alias for "hg help config"
Martin Geisler <mg@lazybytes.net>
parents: 11657
diff changeset
   240
    (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
37998
5fa4e29ba3e3 help: add new deprecated topic
David Demelier <markand@malikania.fr>
parents: 37975
diff changeset
   241
    (['deprecated'], _("Deprecated Features"), loaddoc('deprecated')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   242
    (["dates"], _("Date Formats"), loaddoc('dates')),
35045
b0262b25ab48 help: adding a topic on flags
Rodrigo Damazio Bovendorp <rdamazio@google.com>
parents: 34951
diff changeset
   243
    (["flags"], _("Command-line flags"), loaddoc('flags')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   244
    (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   245
    (['environment', 'env'], _('Environment Variables'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   246
     loaddoc('environment')),
30769
e520f0f4b1cf help: merge revsets.txt into revisions.txt
Martin von Zweigbergk <martinvonz@google.com>
parents: 30610
diff changeset
   247
    (['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],
e520f0f4b1cf help: merge revsets.txt into revisions.txt
Martin von Zweigbergk <martinvonz@google.com>
parents: 30610
diff changeset
   248
      _('Specifying Revisions'), loaddoc('revisions')),
17322
7124f984dc8d help: use the first topic name from helptable, not the longest alias
Mads Kiilerich <mads@kiilerich.com>
parents: 17321
diff changeset
   249
    (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   250
    (['diffs'], _('Diff Formats'), loaddoc('diffs')),
30812
98bfce9bd5e5 help: make "mergetool" an alias for "merge-tools"
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30769
diff changeset
   251
    (['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'),
98bfce9bd5e5 help: make "mergetool" an alias for "merge-tools"
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30769
diff changeset
   252
     loaddoc('merge-tools')),
16568
770190bff625 help: add reference to template help (issue3413)
A. S. Budden <abudden@gmail.com>
parents: 16547
diff changeset
   253
    (['templating', 'templates', 'template', 'style'], _('Template Usage'),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   254
     loaddoc('templates')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   255
    (['urls'], _('URL Paths'), loaddoc('urls')),
16547
23072be2eaa3 help: consistently use title capitalization for help topics
Martin Geisler <mg@aragost.com>
parents: 16250
diff changeset
   256
    (["extensions"], _("Using Additional Features"), extshelp),
17322
7124f984dc8d help: use the first topic name from helptable, not the longest alias
Mads Kiilerich <mads@kiilerich.com>
parents: 17321
diff changeset
   257
    (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')),
17321
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   258
    (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   259
    (["glossary"], _("Glossary"), loaddoc('glossary')),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   260
    (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   261
     loaddoc('hgignore')),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   262
    (["phases"], _("Working with Phases"), loaddoc('phases')),
25881
9de443515f1d help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 25660
diff changeset
   263
    (['scripting'], _('Using Mercurial from scripts and automation'),
9de443515f1d help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 25660
diff changeset
   264
     loaddoc('scripting')),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   265
    (['internals'], _("Technical implementation topics"),
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   266
     internalshelp),
31061
900996da577a pager: move most help to a new help topic and deprecate extension
Augie Fackler <augie@google.com>
parents: 31059
diff changeset
   267
    (['pager'], _("Pager Support"), loaddoc('pager')),
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
   268
])
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   269
27379
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   270
# Maps topics with sub-topics to a list of their sub-topics.
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   271
subtopics = {
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   272
    'internals': internalstable,
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   273
}
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   274
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   275
# Map topics to lists of callable taking the current topic help and
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   276
# returning the updated version
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   277
helphooks = {}
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   278
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   279
def addtopichook(topic, rewriter):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   280
    helphooks.setdefault(topic, []).append(rewriter)
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   281
26414
c44b507e7c78 help: pass around ui to rewriter hooks (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26413
diff changeset
   282
def makeitemsdoc(ui, topic, doc, marker, items, dedent=False):
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   283
    """Extract docstring from the items key to function mapping, build a
26196
3a4620ad4490 help: fix makeitemsdoc English description
timeless@mozdev.org
parents: 25881
diff changeset
   284
    single documentation block and use it to overwrite the marker in doc.
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   285
    """
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   286
    entries = []
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   287
    for name in sorted(items):
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   288
        text = (pycompat.getdoc(items[name]) or '').rstrip()
26415
46af0adb5c37 help: hide deprecated filesets, revsets and template items if not verbose
Yuya Nishihara <yuya@tcha.org>
parents: 26414
diff changeset
   289
        if (not text
46af0adb5c37 help: hide deprecated filesets, revsets and template items if not verbose
Yuya Nishihara <yuya@tcha.org>
parents: 26414
diff changeset
   290
            or not ui.verbose and any(w in text for w in _exclkeywords)):
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   291
            continue
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   292
        text = gettext(text)
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   293
        if dedent:
32549
633c635a790a help: work around textwrap.dedent() only working on strings
Augie Fackler <raf@durin42.com>
parents: 32547
diff changeset
   294
            # Abuse latin1 to use textwrap.dedent() on bytes.
633c635a790a help: work around textwrap.dedent() only working on strings
Augie Fackler <raf@durin42.com>
parents: 32547
diff changeset
   295
            text = textwrap.dedent(text.decode('latin1')).encode('latin1')
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   296
        lines = text.splitlines()
16250
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   297
        doclines = [(lines[0])]
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   298
        for l in lines[1:]:
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   299
            # Stop once we find some Python doctest
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   300
            if l.strip().startswith('>>>'):
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   301
                break
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   302
            if dedent:
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   303
                doclines.append(l.rstrip())
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   304
            else:
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   305
                doclines.append('  ' + l.strip())
16250
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   306
        entries.append('\n'.join(doclines))
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   307
    entries = '\n\n'.join(entries)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   308
    return doc.replace(marker, entries)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   309
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   310
def addtopicsymbols(topic, marker, symbols, dedent=False):
26414
c44b507e7c78 help: pass around ui to rewriter hooks (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26413
diff changeset
   311
    def add(ui, topic, doc):
c44b507e7c78 help: pass around ui to rewriter hooks (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26413
diff changeset
   312
        return makeitemsdoc(ui, topic, doc, marker, symbols, dedent=dedent)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   313
    addtopichook(topic, add)
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   314
31793
69d8fcf20014 help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents: 31293
diff changeset
   315
addtopicsymbols('bundlespec', '.. bundlecompressionmarker',
69d8fcf20014 help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents: 31293
diff changeset
   316
                util.bundlecompressiontopics())
14686
6ab8b17adc03 fileset: add a help topic
Matt Mackall <mpm@selenic.com>
parents: 14318
diff changeset
   317
addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
24099
be83fd9d46d5 help.merge-tools: do not double document merge tools
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24098
diff changeset
   318
addtopicsymbols('merge-tools', '.. internaltoolsmarker',
be83fd9d46d5 help.merge-tools: do not double document merge tools
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24098
diff changeset
   319
                filemerge.internalsdoc)
30769
e520f0f4b1cf help: merge revsets.txt into revisions.txt
Martin von Zweigbergk <martinvonz@google.com>
parents: 30610
diff changeset
   320
addtopicsymbols('revisions', '.. predicatesmarker', revset.symbols)
26436
a2291c9c85a1 templatekw: remove dockeywords hack
Yuya Nishihara <yuya@tcha.org>
parents: 26415
diff changeset
   321
addtopicsymbols('templates', '.. keywordsmarker', templatekw.keywords)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   322
addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)
36922
521f6c7e1756 templater: split template functions to new module
Yuya Nishihara <yuya@tcha.org>
parents: 36451
diff changeset
   323
addtopicsymbols('templates', '.. functionsmarker', templatefuncs.funcs)
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   324
addtopicsymbols('hgweb', '.. webcommandsmarker', webcommands.commands,
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   325
                dedent=True)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   326
32566
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   327
def help_(ui, commands, name, unknowncmd=False, full=True, subtopic=None,
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   328
          **opts):
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   329
    '''
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   330
    Generate the help for 'name' as unformatted restructured text. If
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   331
    'name' is None, describe the commands available.
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   332
    '''
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   333
32143
964c6be36590 py3: make sure opts are passed and used correctly in help command
Pulkit Goyal <7895pulkit@gmail.com>
parents: 32076
diff changeset
   334
    opts = pycompat.byteskwargs(opts)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   335
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   336
    def helpcmd(name, subtopic=None):
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   337
        try:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   338
            aliases, entry = cmdutil.findcmd(name, commands.table,
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   339
                                             strict=unknowncmd)
25660
328739ea70c3 global: mass rewrite to use modern exception syntax
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24871
diff changeset
   340
        except error.AmbiguousCommand as inst:
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   341
            # py3k fix: except vars can't be used outside the scope of the
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   342
            # except block, nor can be used inside a lambda. python issue4617
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   343
            prefix = inst.args[0]
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   344
            select = lambda c: cmdutil.parsealiases(c)[0].startswith(prefix)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   345
            rst = helplist(select)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   346
            return rst
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   347
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   348
        rst = []
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   349
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   350
        # check if it's an invalid alias and display its error if it is
22160
645457f73aa6 alias: keep error message in "badalias" so that help can see it
Yuya Nishihara <yuya@tcha.org>
parents: 22118
diff changeset
   351
        if getattr(entry[0], 'badalias', None):
22162
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   352
            rst.append(entry[0].badalias + '\n')
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   353
            if entry[0].unknowncmd:
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   354
                try:
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   355
                    rst.extend(helpextcmd(entry[0].cmdname))
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   356
                except error.UnknownCommand:
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   357
                    pass
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   358
            return rst
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   359
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   360
        # synopsis
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   361
        if len(entry) > 2:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   362
            if entry[2].startswith('hg'):
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   363
                rst.append("%s\n" % entry[2])
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   364
            else:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   365
                rst.append('hg %s %s\n' % (aliases[0], entry[2]))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   366
        else:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   367
            rst.append('hg %s\n' % aliases[0])
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   368
        # aliases
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   369
        if full and not ui.quiet and len(aliases) > 1:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   370
            rst.append(_("\naliases: %s\n") % ', '.join(aliases[1:]))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   371
        rst.append('\n')
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   372
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   373
        # description
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   374
        doc = gettext(pycompat.getdoc(entry[0]))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   375
        if not doc:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   376
            doc = _("(no help text available)")
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   377
        if util.safehasattr(entry[0], 'definition'):  # aliased command
28828
3640c1702c43 help: report source of aliases
timeless <timeless@mozdev.org>
parents: 28523
diff changeset
   378
            source = entry[0].source
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   379
            if entry[0].definition.startswith('!'):  # shell alias
37134
6890b7e991a4 help: supporting both help and doc for aliases
Rodrigo Damazio <rdamazio@google.com>
parents: 37092
diff changeset
   380
                doc = (_('shell alias for: %s\n\n%s\n\ndefined by: %s\n') %
6890b7e991a4 help: supporting both help and doc for aliases
Rodrigo Damazio <rdamazio@google.com>
parents: 37092
diff changeset
   381
                       (entry[0].definition[1:], doc, source))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   382
            else:
28828
3640c1702c43 help: report source of aliases
timeless <timeless@mozdev.org>
parents: 28523
diff changeset
   383
                doc = (_('alias for: hg %s\n\n%s\n\ndefined by: %s\n') %
3640c1702c43 help: report source of aliases
timeless <timeless@mozdev.org>
parents: 28523
diff changeset
   384
                       (entry[0].definition, doc, source))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   385
        doc = doc.splitlines(True)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   386
        if ui.quiet or not full:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   387
            rst.append(doc[0])
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   388
        else:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   389
            rst.extend(doc)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   390
        rst.append('\n')
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   391
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   392
        # check if this command shadows a non-trivial (multi-line)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   393
        # extension help text
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   394
        try:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   395
            mod = extensions.find(name)
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   396
            doc = gettext(pycompat.getdoc(mod)) or ''
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   397
            if '\n' in doc.strip():
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   398
                msg = _("(use 'hg help -e %s' to show help for "
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   399
                        "the %s extension)") % (name, name)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   400
                rst.append('\n%s\n' % msg)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   401
        except KeyError:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   402
            pass
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   403
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   404
        # options
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   405
        if not ui.quiet and entry[1]:
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   406
            rst.append(optrst(_("options"), entry[1], ui.verbose))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   407
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   408
        if ui.verbose:
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   409
            rst.append(optrst(_("global options"),
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   410
                              commands.globalopts, ui.verbose))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   411
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   412
        if not ui.verbose:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   413
            if not full:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   414
                rst.append(_("\n(use 'hg %s -h' to show more help)\n")
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   415
                           % name)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   416
            elif not ui.quiet:
22110
26f7c8033bed help: tweak --verbose command help hint
Matt Mackall <mpm@selenic.com>
parents: 21796
diff changeset
   417
                rst.append(_('\n(some details hidden, use --verbose '
26f7c8033bed help: tweak --verbose command help hint
Matt Mackall <mpm@selenic.com>
parents: 21796
diff changeset
   418
                               'to show complete help)'))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   419
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   420
        return rst
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   421
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   422
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   423
    def helplist(select=None, **opts):
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   424
        # list of commands
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   425
        if name == "shortlist":
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   426
            header = _('basic commands:\n\n')
20822
be87397f98c9 help: let 'hg help debug' show the list of secret debug commands
Mads Kiilerich <madski@unity3d.com>
parents: 20743
diff changeset
   427
        elif name == "debug":
be87397f98c9 help: let 'hg help debug' show the list of secret debug commands
Mads Kiilerich <madski@unity3d.com>
parents: 20743
diff changeset
   428
            header = _('debug commands (internal and unsupported):\n\n')
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   429
        else:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   430
            header = _('list of commands:\n\n')
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   431
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   432
        h = {}
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   433
        cmds = {}
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   434
        for c, e in commands.table.iteritems():
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   435
            fs = cmdutil.parsealiases(c)
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   436
            f = fs[0]
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   437
            p = ''
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   438
            if c.startswith("^"):
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   439
                p = '^'
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   440
            if select and not select(p + f):
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   441
                continue
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   442
            if (not select and name != 'shortlist' and
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   443
                e[0].__module__ != commands.__name__):
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   444
                continue
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   445
            if name == "shortlist" and not p:
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   446
                continue
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   447
            doc = pycompat.getdoc(e[0])
27323
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   448
            if filtercmd(ui, f, name, doc):
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   449
                continue
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   450
            doc = gettext(doc)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   451
            if not doc:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   452
                doc = _("(no help text available)")
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   453
            h[f] = doc.splitlines()[0].rstrip()
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   454
            cmds[f] = '|'.join(fs)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   455
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   456
        rst = []
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   457
        if not h:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   458
            if not ui.quiet:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   459
                rst.append(_('no commands defined\n'))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   460
            return rst
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   461
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   462
        if not ui.quiet:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   463
            rst.append(header)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   464
        fns = sorted(h)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   465
        for f in fns:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   466
            if ui.verbose:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   467
                commacmds = cmds[f].replace("|",", ")
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   468
                rst.append(" :%s: %s\n" % (commacmds, h[f]))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   469
            else:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   470
                rst.append(' :%s: %s\n' % (f, h[f]))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   471
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   472
        ex = opts.get
35356
7f410793c04d py3: handle keyword arguments correctly in help.py
Pulkit Goyal <7895pulkit@gmail.com>
parents: 35045
diff changeset
   473
        anyopts = (ex(r'keyword') or not (ex(r'command') or ex(r'extension')))
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   474
        if not name and anyopts:
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   475
            exts = listexts(_('enabled extensions:'), extensions.enabled())
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   476
            if exts:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   477
                rst.append('\n')
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   478
                rst.extend(exts)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   479
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   480
            rst.append(_("\nadditional help topics:\n\n"))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   481
            topics = []
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   482
            for names, header, doc in helptable:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   483
                topics.append((names[0], header))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   484
            for t, desc in topics:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   485
                rst.append(" :%s: %s\n" % (t, desc))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   486
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   487
        if ui.quiet:
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   488
            pass
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   489
        elif ui.verbose:
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   490
            rst.append('\n%s\n' % optrst(_("global options"),
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   491
                                         commands.globalopts, ui.verbose))
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   492
            if name == 'shortlist':
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   493
                rst.append(_("\n(use 'hg help' for the full list "
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   494
                             "of commands)\n"))
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   495
        else:
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   496
            if name == 'shortlist':
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   497
                rst.append(_("\n(use 'hg help' for the full list of commands "
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   498
                             "or 'hg -v' for details)\n"))
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   499
            elif name and not full:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   500
                rst.append(_("\n(use 'hg help %s' to show the full help "
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   501
                             "text)\n") % name)
23624
861ddedfb402 help: suggest '-v -e' to get built-in aliases for extensions (issue4461)
Chingis Dugarzhapov <chingis.dug@gmail.com>
parents: 22637
diff changeset
   502
            elif name and cmds and name in cmds.keys():
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   503
                rst.append(_("\n(use 'hg help -v -e %s' to show built-in "
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   504
                             "aliases and global options)\n") % name)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   505
            else:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   506
                rst.append(_("\n(use 'hg help -v%s' to show built-in aliases "
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   507
                             "and global options)\n")
22118
9a299c39de01 help: normalize helplist hints
Matt Mackall <mpm@selenic.com>
parents: 22117
diff changeset
   508
                           % (name and " " + name or ""))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   509
        return rst
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   510
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   511
    def helptopic(name, subtopic=None):
27379
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   512
        # Look for sub-topic entry first.
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   513
        header, doc = None, None
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   514
        if subtopic and name in subtopics:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   515
            for names, header, doc in subtopics[name]:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   516
                if subtopic in names:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   517
                    break
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   518
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   519
        if not header:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   520
            for names, header, doc in helptable:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   521
                if name in names:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   522
                    break
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   523
            else:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   524
                raise error.UnknownCommand(name)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   525
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 18746
diff changeset
   526
        rst = [minirst.section(header)]
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 18746
diff changeset
   527
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   528
        # description
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   529
        if not doc:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   530
            rst.append("    %s\n" % _("(no help text available)"))
21796
8225bb1f0ad3 help: restore use of callable() since it was readded in Python 3.2
Augie Fackler <raf@durin42.com>
parents: 21289
diff changeset
   531
        if callable(doc):
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   532
            rst += ["    %s\n" % l for l in doc(ui).splitlines()]
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   533
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   534
        if not ui.verbose:
22114
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   535
            omitted = _('(some details hidden, use --verbose'
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   536
                         ' to show complete help)')
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   537
            indicateomitted(rst, omitted)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   538
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   539
        try:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   540
            cmdutil.findcmd(name, commands.table)
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   541
            rst.append(_("\nuse 'hg help -c %s' to see help for "
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   542
                       "the %s command\n") % (name, name))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   543
        except error.UnknownCommand:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   544
            pass
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   545
        return rst
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   546
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   547
    def helpext(name, subtopic=None):
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   548
        try:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   549
            mod = extensions.find(name)
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   550
            doc = gettext(pycompat.getdoc(mod)) or _('no help text available')
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   551
        except KeyError:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   552
            mod = None
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   553
            doc = extensions.disabledext(name)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   554
            if not doc:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   555
                raise error.UnknownCommand(name)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   556
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   557
        if '\n' not in doc:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   558
            head, tail = doc, ""
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   559
        else:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   560
            head, tail = doc.split('\n', 1)
26845
7a77ee434179 help: replace some str.split() calls by str.partition() or str.rpartition()
Anton Shestakov <av6@dwimlabs.net>
parents: 26587
diff changeset
   561
        rst = [_('%s extension - %s\n\n') % (name.rpartition('.')[-1], head)]
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   562
        if tail:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   563
            rst.extend(tail.splitlines(True))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   564
            rst.append('\n')
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   565
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   566
        if not ui.verbose:
22114
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   567
            omitted = _('(some details hidden, use --verbose'
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   568
                         ' to show complete help)')
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   569
            indicateomitted(rst, omitted)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   570
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   571
        if mod:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   572
            try:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   573
                ct = mod.cmdtable
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   574
            except AttributeError:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   575
                ct = {}
26845
7a77ee434179 help: replace some str.split() calls by str.partition() or str.rpartition()
Anton Shestakov <av6@dwimlabs.net>
parents: 26587
diff changeset
   576
            modcmds = set([c.partition('|')[0] for c in ct])
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   577
            rst.extend(helplist(modcmds.__contains__))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   578
        else:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   579
            rst.append(_("(use 'hg help extensions' for information on enabling"
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   580
                       " extensions)\n"))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   581
        return rst
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   582
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   583
    def helpextcmd(name, subtopic=None):
37975
6e526b0961a8 help: load module doc of disabled extension in extensions.disabledcmd()
Yuya Nishihara <yuya@tcha.org>
parents: 37134
diff changeset
   584
        cmd, ext, doc = extensions.disabledcmd(ui, name,
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   585
                                               ui.configbool('ui', 'strict'))
37975
6e526b0961a8 help: load module doc of disabled extension in extensions.disabledcmd()
Yuya Nishihara <yuya@tcha.org>
parents: 37134
diff changeset
   586
        doc = doc.splitlines()[0]
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   587
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   588
        rst = listexts(_("'%s' is provided by the following "
27152
ac27b1b3be85 help: make help deprecated mention the extension
timeless <timeless@mozdev.org>
parents: 27151
diff changeset
   589
                              "extension:") % cmd, {ext: doc}, indent=4,
ac27b1b3be85 help: make help deprecated mention the extension
timeless <timeless@mozdev.org>
parents: 27151
diff changeset
   590
                       showdeprecated=True)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   591
        rst.append('\n')
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   592
        rst.append(_("(use 'hg help extensions' for information on enabling "
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   593
                   "extensions)\n"))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   594
        return rst
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   595
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   596
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   597
    rst = []
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   598
    kw = opts.get('keyword')
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   599
    if kw or name is None and any(opts[o] for o in opts):
32566
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   600
        matches = topicmatch(ui, commands, name or '')
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   601
        helpareas = []
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   602
        if opts.get('extension'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   603
            helpareas += [('extensions', _('Extensions'))]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   604
        if opts.get('command'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   605
            helpareas += [('commands', _('Commands'))]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   606
        if not helpareas:
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   607
            helpareas = [('topics', _('Topics')),
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   608
                         ('commands', _('Commands')),
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   609
                         ('extensions', _('Extensions')),
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   610
                         ('extensioncommands', _('Extension Commands'))]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   611
        for t, title in helpareas:
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   612
            if matches[t]:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   613
                rst.append('%s:\n\n' % title)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   614
                rst.extend(minirst.maketable(sorted(matches[t]), 1))
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   615
                rst.append('\n')
21288
eb6eaef7ae44 help: provide a more helpful message when no keyword are matched
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 20823
diff changeset
   616
        if not rst:
eb6eaef7ae44 help: provide a more helpful message when no keyword are matched
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 20823
diff changeset
   617
            msg = _('no matches')
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   618
            hint = _("try 'hg help' for a list of topics")
26587
56b2bcea2529 error: get Abort from 'error' instead of 'util'
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 26436
diff changeset
   619
            raise error.Abort(msg, hint=hint)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   620
    elif name and name != 'shortlist':
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   621
        queries = []
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   622
        if unknowncmd:
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   623
            queries += [helpextcmd]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   624
        if opts.get('extension'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   625
            queries += [helpext]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   626
        if opts.get('command'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   627
            queries += [helpcmd]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   628
        if not queries:
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   629
            queries = (helptopic, helpcmd, helpext, helpextcmd)
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   630
        for f in queries:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   631
            try:
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   632
                rst = f(name, subtopic)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   633
                break
21289
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   634
            except error.UnknownCommand:
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   635
                pass
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   636
        else:
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   637
            if unknowncmd:
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   638
                raise error.UnknownCommand(name)
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   639
            else:
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   640
                msg = _('no such help topic: %s') % name
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   641
                hint = _("try 'hg help --keyword %s'") % name
26587
56b2bcea2529 error: get Abort from 'error' instead of 'util'
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 26436
diff changeset
   642
                raise error.Abort(msg, hint=hint)
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   643
    else:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   644
        # program name
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   645
        if not ui.quiet:
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   646
            rst = [_("Mercurial Distributed SCM\n"), '\n']
32547
0cec8ad579d4 help: convert dict to strkwargs
Augie Fackler <raf@durin42.com>
parents: 32291
diff changeset
   647
        rst.extend(helplist(None, **pycompat.strkwargs(opts)))
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   648
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   649
    return ''.join(rst)
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   650
39339
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   651
def formattedhelp(ui, commands, fullname, keep=None, unknowncmd=False,
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   652
                  full=True, **opts):
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   653
    """get help for a given topic (as a dotted name) as rendered rst
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   654
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   655
    Either returns the rendered help text or raises an exception.
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   656
    """
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   657
    if keep is None:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   658
        keep = []
31265
79715ba22f9c help: avoid mutating passed-in `keep` list in `formattedhelp`
Augie Fackler <augie@google.com>
parents: 31129
diff changeset
   659
    else:
79715ba22f9c help: avoid mutating passed-in `keep` list in `formattedhelp`
Augie Fackler <augie@google.com>
parents: 31129
diff changeset
   660
        keep = list(keep) # make a copy so we can mutate this later
39339
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   661
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   662
    # <fullname> := <name>[.<subtopic][.<section>]
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   663
    name = subtopic = section = None
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   664
    if fullname is not None:
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   665
        nameparts = fullname.split('.')
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   666
        name = nameparts.pop(0)
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   667
        if nameparts and name in subtopics:
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   668
            subtopic = nameparts.pop(0)
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   669
        if nameparts:
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   670
            section = encoding.lower('.'.join(nameparts))
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   671
33499
0407a51b9d8c codemod: register core configitems using a script
Jun Wu <quark@fb.com>
parents: 32619
diff changeset
   672
    textwidth = ui.configint('ui', 'textwidth')
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   673
    termwidth = ui.termwidth() - 2
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   674
    if textwidth <= 0 or termwidth < textwidth:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   675
        textwidth = termwidth
32566
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   676
    text = help_(ui, commands, name,
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   677
                 subtopic=subtopic, unknowncmd=unknowncmd, full=full, **opts)
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   678
39308
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   679
    blocks, pruned = minirst.parse(text, keep=keep)
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   680
    if 'verbose' in pruned:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   681
        keep.append('omitted')
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   682
    else:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   683
        keep.append('notomitted')
39308
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   684
    blocks, pruned = minirst.parse(text, keep=keep)
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   685
    if section:
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   686
        blocks = minirst.filtersections(blocks, section)
39309
0a766cb1092a help: reorder section filtering flow to not format help text twice
Yuya Nishihara <yuya@tcha.org>
parents: 39308
diff changeset
   687
0a766cb1092a help: reorder section filtering flow to not format help text twice
Yuya Nishihara <yuya@tcha.org>
parents: 39308
diff changeset
   688
    # We could have been given a weird ".foo" section without a name
0a766cb1092a help: reorder section filtering flow to not format help text twice
Yuya Nishihara <yuya@tcha.org>
parents: 39308
diff changeset
   689
    # to look for, or we could have simply failed to found "foo.bar"
0a766cb1092a help: reorder section filtering flow to not format help text twice
Yuya Nishihara <yuya@tcha.org>
parents: 39308
diff changeset
   690
    # because bar isn't a section of foo
0a766cb1092a help: reorder section filtering flow to not format help text twice
Yuya Nishihara <yuya@tcha.org>
parents: 39308
diff changeset
   691
    if section and not (blocks and name):
0a766cb1092a help: reorder section filtering flow to not format help text twice
Yuya Nishihara <yuya@tcha.org>
parents: 39308
diff changeset
   692
        raise error.Abort(_("help section not found: %s") % fullname)
0a766cb1092a help: reorder section filtering flow to not format help text twice
Yuya Nishihara <yuya@tcha.org>
parents: 39308
diff changeset
   693
39308
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   694
    return minirst.formatplain(blocks, textwidth)