mercurial/help.py
author rdamazio@google.com
Sat, 13 Oct 2018 02:17:41 -0700
changeset 40293 c303d65d2e34
parent 40292 9c6473d2038b
child 40294 fabbf9310025
permissions -rw-r--r--
help: assigning categories to existing commands I'm separating this into its own commit so people can bikeshed over the actual categorization (vs the support for categories). These categories are based on the help implementation we've been using internally at Google, and have had zero complaints. Differential Revision: https://phab.mercurial-scm.org/D5067
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,
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    28
    registrar,
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    29
    revset,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    30
    templatefilters,
36922
521f6c7e1756 templater: split template functions to new module
Yuya Nishihara <yuya@tcha.org>
parents: 36451
diff changeset
    31
    templatefuncs,
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    32
    templatekw,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    33
    util,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    34
)
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    35
from .hgweb import (
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    36
    webcommands,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    37
)
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
    38
32291
bd872f64a8ba cleanup: use set literals
Martin von Zweigbergk <martinvonz@google.com>
parents: 32143
diff changeset
    39
_exclkeywords = {
31080
6918c9215201 help: hide command line options marked as "advanced"
Jun Wu <quark@fb.com>
parents: 31061
diff changeset
    40
    "(ADVANCED)",
26370
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    41
    "(DEPRECATED)",
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    42
    "(EXPERIMENTAL)",
31080
6918c9215201 help: hide command line options marked as "advanced"
Jun Wu <quark@fb.com>
parents: 31061
diff changeset
    43
    # 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
    44
    _("(ADVANCED)"),
26370
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    45
    # 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
    46
    _("(DEPRECATED)"),
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    47
    # 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
    48
    _("(EXPERIMENTAL)"),
32291
bd872f64a8ba cleanup: use set literals
Martin von Zweigbergk <martinvonz@google.com>
parents: 32143
diff changeset
    49
}
26369
4799b5c4aaf4 help: define list of keywords that should be excluded from non-verbose output
Yuya Nishihara <yuya@tcha.org>
parents: 26238
diff changeset
    50
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    51
# The order in which command categories will be displayed.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    52
# Extensions with custom categories should insert them into this list
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    53
# after/before the appropriate item, rather than replacing the list or
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    54
# assuming absolute positions.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    55
CATEGORY_ORDER = [
40293
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    56
    registrar.command.CATEGORY_REPO_CREATION,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    57
    registrar.command.CATEGORY_REMOTE_REPO_MANAGEMENT,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    58
    registrar.command.CATEGORY_COMMITTING,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    59
    registrar.command.CATEGORY_CHANGE_MANAGEMENT,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    60
    registrar.command.CATEGORY_CHANGE_ORGANIZATION,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    61
    registrar.command.CATEGORY_FILE_CONTENTS,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    62
    registrar.command.CATEGORY_CHANGE_NAVIGATION ,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    63
    registrar.command.CATEGORY_WORKING_DIRECTORY,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    64
    registrar.command.CATEGORY_IMPORT_EXPORT,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    65
    registrar.command.CATEGORY_MAINTENANCE,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    66
    registrar.command.CATEGORY_HELP,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    67
    registrar.command.CATEGORY_MISC,
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    68
    registrar.command.CATEGORY_NONE,
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    69
]
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    70
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    71
# Human-readable category names. These are translated.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    72
# Extensions with custom categories should add their names here.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    73
CATEGORY_NAMES = {
40293
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    74
    registrar.command.CATEGORY_REPO_CREATION: 'Repository creation',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    75
    registrar.command.CATEGORY_REMOTE_REPO_MANAGEMENT:
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    76
        'Remote repository management',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    77
    registrar.command.CATEGORY_COMMITTING: 'Change creation',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    78
    registrar.command.CATEGORY_CHANGE_NAVIGATION: 'Change navigation',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    79
    registrar.command.CATEGORY_CHANGE_MANAGEMENT: 'Change manipulation',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    80
    registrar.command.CATEGORY_CHANGE_ORGANIZATION: 'Change organization',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    81
    registrar.command.CATEGORY_WORKING_DIRECTORY:
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    82
        'Working directory management',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    83
    registrar.command.CATEGORY_FILE_CONTENTS: 'File content management',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    84
    registrar.command.CATEGORY_IMPORT_EXPORT: 'Change import/export',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    85
    registrar.command.CATEGORY_MAINTENANCE: 'Repository maintenance',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    86
    registrar.command.CATEGORY_HELP: 'Help',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    87
    registrar.command.CATEGORY_MISC: 'Miscellaneous commands',
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    88
    registrar.command.CATEGORY_NONE: 'Uncategorized commands',
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    89
}
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    90
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    91
# Topic categories.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    92
TOPIC_CATEGORY_NONE = 'none'
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    93
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    94
# The order in which topic categories will be displayed.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    95
# Extensions with custom categories should insert them into this list
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    96
# after/before the appropriate item, rather than replacing the list or
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    97
# assuming absolute positions.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    98
TOPIC_CATEGORY_ORDER = [
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    99
    TOPIC_CATEGORY_NONE,
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   100
]
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   101
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   102
# Human-readable topic category names. These are translated.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   103
TOPIC_CATEGORY_NAMES = {
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   104
    TOPIC_CATEGORY_NONE: 'Uncategorized topics',
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   105
}
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   106
20582
02c303f64917 help: exclude deprecated extensions in the disabled part of 'help extensions'
Augie Fackler <raf@durin42.com>
parents: 20034
diff changeset
   107
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
   108
    '''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
   109
    rst = []
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
   110
    if exts:
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
   111
        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
   112
            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
   113
                continue
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
   114
            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
   115
    if rst:
7625f6387fc4 help: make listexts less confusing for deprecated exts
timeless <timeless@mozdev.org>
parents: 26845
diff changeset
   116
        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
   117
    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
   118
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   119
def extshelp(ui):
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   120
    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
   121
    rst.extend(listexts(
02c303f64917 help: exclude deprecated extensions in the disabled part of 'help extensions'
Augie Fackler <raf@durin42.com>
parents: 20034
diff changeset
   122
        _('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
   123
    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
   124
                        showdeprecated=ui.verbose))
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
   125
    doc = ''.join(rst)
8863
7b19c3c0172b help: adding a new help topic about extensions
C?dric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
   126
    return doc
7013
f56e788fa292 i18n: mark help strings for translation
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
   127
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   128
def optrst(header, options, verbose):
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   129
    data = []
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   130
    multioccur = False
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   131
    for option in options:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   132
        if len(option) == 5:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   133
            shortopt, longopt, default, desc, optlabel = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   134
        else:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   135
            shortopt, longopt, default, desc = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   136
            optlabel = _("VALUE") # default label
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   137
26369
4799b5c4aaf4 help: define list of keywords that should be excluded from non-verbose output
Yuya Nishihara <yuya@tcha.org>
parents: 26238
diff changeset
   138
        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
   139
            continue
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   140
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   141
        so = ''
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   142
        if shortopt:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   143
            so = '-' + shortopt
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   144
        lo = '--' + longopt
37091
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
   145
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
   146
        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
   147
            default = default.getdefaultvalue()
37091
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
   148
        if default and not callable(default):
32619
d110fb58424c help: convert flag default to bytes portably
Augie Fackler <raf@durin42.com>
parents: 32615
diff changeset
   149
            # 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
   150
            # 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
   151
            # 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
   152
            # then convert it to bytes.
d110fb58424c help: convert flag default to bytes portably
Augie Fackler <raf@durin42.com>
parents: 32615
diff changeset
   153
            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
   154
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   155
        if isinstance(default, list):
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   156
            lo += " %s [+]" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   157
            multioccur = True
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   158
        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
   159
            lo += " %s" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   160
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   161
        data.append((so, lo, desc))
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   162
22117
c1d93edcf004 help: fold repeatable option message into option table header
Matt Mackall <mpm@selenic.com>
parents: 22116
diff changeset
   163
    if multioccur:
c1d93edcf004 help: fold repeatable option message into option table header
Matt Mackall <mpm@selenic.com>
parents: 22116
diff changeset
   164
        header += (_(" ([+] can be repeated)"))
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   165
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   166
    rst = ['\n%s:\n\n' % header]
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   167
    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
   168
16815
e740746ea557 minirst: generate tables as a list of joined lines
Olav Reinert <seroton10@gmail.com>
parents: 16781
diff changeset
   169
    return ''.join(rst)
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   170
17837
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
   171
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
   172
    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
   173
    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
   174
        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
   175
27323
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   176
def filtercmd(ui, cmd, kw, doc):
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   177
    if not ui.debugflag and cmd.startswith("debug") and kw != "debug":
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   178
        return True
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   179
    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
   180
        return True
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   181
    return False
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   182
32566
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   183
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
   184
    """Return help topics matching kw.
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   185
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   186
    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
   187
    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
   188
    """
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   189
    kw = encoding.lower(kw)
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   190
    def lowercontains(container):
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   191
        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
   192
    results = {'topics': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   193
               'commands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   194
               'extensions': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   195
               'extensioncommands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   196
               }
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   197
    for topic in helptable:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   198
        names, header, doc = topic[0:3]
22322
e284de138f00 help: only call doc() when it is callable
Gregory Szorc <gregory.szorc@gmail.com>
parents: 21796
diff changeset
   199
        # 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
   200
        if (sum(map(lowercontains, names))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   201
            or lowercontains(header)
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   202
            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
   203
            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
   204
    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
   205
        if len(entry) == 3:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   206
            summary = entry[2]
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   207
        else:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   208
            summary = ''
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   209
        # 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
   210
        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
   211
        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
   212
            doclines = docs.splitlines()
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   213
            if doclines:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   214
                summary = doclines[0]
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   215
            cmdname = cmdutil.parsealiases(cmd)[0]
27324
5456374561a7 help: call filtercmd from topicmatch
timeless <timeless@mozdev.org>
parents: 27323
diff changeset
   216
            if filtercmd(ui, cmdname, kw, docs):
5456374561a7 help: call filtercmd from topicmatch
timeless <timeless@mozdev.org>
parents: 27323
diff changeset
   217
                continue
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   218
            results['commands'].append((cmdname, summary))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   219
    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
   220
        extensions.enabled(False).iteritems(),
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   221
        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
   222
        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
   223
            continue
26845
7a77ee434179 help: replace some str.split() calls by str.partition() or str.rpartition()
Anton Shestakov <av6@dwimlabs.net>
parents: 26587
diff changeset
   224
        name = name.rpartition('.')[-1]
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   225
        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
   226
            # 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
   227
            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
   228
        try:
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   229
            mod = extensions.load(ui, name, '')
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   230
        except ImportError:
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   231
            # 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
   232
            continue
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   233
        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
   234
            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
   235
                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
   236
                cmddoc = pycompat.getdoc(entry[0])
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   237
                if cmddoc:
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   238
                    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
   239
                else:
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
   240
                    cmddoc = _('(no help text available)')
27387
dfab0afde928 help: filter extension commands
timeless <timeless@mozdev.org>
parents: 27379
diff changeset
   241
                if filtercmd(ui, cmdname, kw, cmddoc):
dfab0afde928 help: filter extension commands
timeless <timeless@mozdev.org>
parents: 27379
diff changeset
   242
                    continue
16884
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
   243
                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
   244
    return results
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   245
27375
c4a062d090ee help: teach loaddoc to load from a different directory
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27325
diff changeset
   246
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
   247
    """Return a delayed loader for help/topic.txt."""
3798
6f0c42d50394 move environment topic
Matt Mackall <mpm@selenic.com>
parents: 3795
diff changeset
   248
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   249
    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
   250
        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
   251
        if subdir:
c4a062d090ee help: teach loaddoc to load from a different directory
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27325
diff changeset
   252
            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
   253
        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
   254
        doc = gettext(util.readfile(path))
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   255
        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
   256
            doc = rewriter(ui, topic, doc)
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   257
        return doc
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   258
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   259
    return loader
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
   260
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   261
internalstable = sorted([
36451
1fa35ca345a5 internals: document bundle2 format
Gregory Szorc <gregory.szorc@gmail.com>
parents: 36250
diff changeset
   262
    (['bundle2'], _('Bundle2'),
1fa35ca345a5 internals: document bundle2 format
Gregory Szorc <gregory.szorc@gmail.com>
parents: 36250
diff changeset
   263
     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
   264
    (['bundles'], _('Bundles'),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   265
     loaddoc('bundles', subdir='internals')),
39409
2fe21c65777e internals: document CBOR utilization
Gregory Szorc <gregory.szorc@gmail.com>
parents: 39339
diff changeset
   266
    (['cbor'], _('CBOR'),
2fe21c65777e internals: document CBOR utilization
Gregory Szorc <gregory.szorc@gmail.com>
parents: 39339
diff changeset
   267
     loaddoc('cbor', subdir='internals')),
31293
2cdb1239ff8c help: update help.internalstable for new censor docs
Augie Fackler <augie@google.com>
parents: 31265
diff changeset
   268
    (['censor'], _('Censor'),
2cdb1239ff8c help: update help.internalstable for new censor docs
Augie Fackler <augie@google.com>
parents: 31265
diff changeset
   269
     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
   270
    (['changegroups'], _('Changegroups'),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   271
     loaddoc('changegroups', subdir='internals')),
34951
fb7f58daca48 internals: copy-edit "register" -> "registrar" in configitem docs
Kevin Bullock <kbullock+mercurial@ringworld.org>
parents: 34932
diff changeset
   272
    (['config'], _('Config Registrar'),
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents: 34912
diff changeset
   273
     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
   274
    (['requirements'], _('Repository Requirements'),
28523
045fe7042510 help: document requirements
Gregory Szorc <gregory.szorc@gmail.com>
parents: 28058
diff changeset
   275
     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
   276
    (['revlogs'], _('Revision Logs'),
27631
c18292a6ff54 internals: document revlog format
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27479
diff changeset
   277
     loaddoc('revlogs', subdir='internals')),
29859
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29747
diff changeset
   278
    (['wireprotocol'], _('Wire Protocol'),
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29747
diff changeset
   279
     loaddoc('wireprotocol', subdir='internals')),
39614
a2880ac67ee0 help: add internals.wireprotocolrpc to the table
Yuya Nishihara <yuya@tcha.org>
parents: 39461
diff changeset
   280
    (['wireprotocolrpc'], _('Wire Protocol RPC'),
a2880ac67ee0 help: add internals.wireprotocolrpc to the table
Yuya Nishihara <yuya@tcha.org>
parents: 39461
diff changeset
   281
     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
   282
    (['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
   283
     loaddoc('wireprotocolv2', subdir='internals')),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   284
])
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   285
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   286
def internalshelp(ui):
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   287
    """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
   288
    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
   289
             '\n']
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   290
    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
   291
        lines.append(' :%s: %s\n' % (names[0], header))
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   292
27400
64208bd4c580 help: add missed last new line to "internals" topic
Yuya Nishihara <yuya@tcha.org>
parents: 27387
diff changeset
   293
    return ''.join(lines)
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   294
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
   295
helptable = sorted([
31793
69d8fcf20014 help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents: 31293
diff changeset
   296
    (['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
   297
    (['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
   298
    (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
37998
5fa4e29ba3e3 help: add new deprecated topic
David Demelier <markand@malikania.fr>
parents: 37975
diff changeset
   299
    (['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
   300
    (["dates"], _("Date Formats"), loaddoc('dates')),
35045
b0262b25ab48 help: adding a topic on flags
Rodrigo Damazio Bovendorp <rdamazio@google.com>
parents: 34951
diff changeset
   301
    (["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
   302
    (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   303
    (['environment', 'env'], _('Environment Variables'),
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   304
     loaddoc('environment')),
30769
e520f0f4b1cf help: merge revsets.txt into revisions.txt
Martin von Zweigbergk <martinvonz@google.com>
parents: 30610
diff changeset
   305
    (['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],
e520f0f4b1cf help: merge revsets.txt into revisions.txt
Martin von Zweigbergk <martinvonz@google.com>
parents: 30610
diff changeset
   306
      _('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
   307
    (['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
   308
    (['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
   309
    (['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
   310
     loaddoc('merge-tools')),
16568
770190bff625 help: add reference to template help (issue3413)
A. S. Budden <abudden@gmail.com>
parents: 16547
diff changeset
   311
    (['templating', 'templates', 'template', 'style'], _('Template Usage'),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   312
     loaddoc('templates')),
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   313
    (['urls'], _('URL Paths'), loaddoc('urls')),
16547
23072be2eaa3 help: consistently use title capitalization for help topics
Martin Geisler <mg@aragost.com>
parents: 16250
diff changeset
   314
    (["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
   315
    (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos')),
17321
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   316
    (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   317
    (["glossary"], _("Glossary"), loaddoc('glossary')),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   318
    (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   319
     loaddoc('hgignore')),
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   320
    (["phases"], _("Working with Phases"), loaddoc('phases')),
25881
9de443515f1d help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 25660
diff changeset
   321
    (['scripting'], _('Using Mercurial from scripts and automation'),
9de443515f1d help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 25660
diff changeset
   322
     loaddoc('scripting')),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   323
    (['internals'], _("Technical implementation topics"),
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   324
     internalshelp),
31061
900996da577a pager: move most help to a new help topic and deprecate extension
Augie Fackler <augie@google.com>
parents: 31059
diff changeset
   325
    (['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
   326
])
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   327
27379
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   328
# 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
   329
subtopics = {
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   330
    'internals': internalstable,
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   331
}
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   332
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   333
# 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
   334
# returning the updated version
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   335
helphooks = {}
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   336
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   337
def addtopichook(topic, rewriter):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   338
    helphooks.setdefault(topic, []).append(rewriter)
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   339
26414
c44b507e7c78 help: pass around ui to rewriter hooks (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26413
diff changeset
   340
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
   341
    """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
   342
    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
   343
    """
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   344
    entries = []
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   345
    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
   346
        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
   347
        if (not text
46af0adb5c37 help: hide deprecated filesets, revsets and template items if not verbose
Yuya Nishihara <yuya@tcha.org>
parents: 26414
diff changeset
   348
            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
   349
            continue
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   350
        text = gettext(text)
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   351
        if dedent:
32549
633c635a790a help: work around textwrap.dedent() only working on strings
Augie Fackler <raf@durin42.com>
parents: 32547
diff changeset
   352
            # 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
   353
            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
   354
        lines = text.splitlines()
16250
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   355
        doclines = [(lines[0])]
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   356
        for l in lines[1:]:
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   357
            # 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
   358
            if l.strip().startswith('>>>'):
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   359
                break
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   360
            if dedent:
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   361
                doclines.append(l.rstrip())
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   362
            else:
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   363
                doclines.append('  ' + l.strip())
16250
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   364
        entries.append('\n'.join(doclines))
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   365
    entries = '\n\n'.join(entries)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   366
    return doc.replace(marker, entries)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   367
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   368
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
   369
    def add(ui, topic, doc):
c44b507e7c78 help: pass around ui to rewriter hooks (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26413
diff changeset
   370
        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
   371
    addtopichook(topic, add)
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   372
31793
69d8fcf20014 help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents: 31293
diff changeset
   373
addtopicsymbols('bundlespec', '.. bundlecompressionmarker',
69d8fcf20014 help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents: 31293
diff changeset
   374
                util.bundlecompressiontopics())
14686
6ab8b17adc03 fileset: add a help topic
Matt Mackall <mpm@selenic.com>
parents: 14318
diff changeset
   375
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
   376
addtopicsymbols('merge-tools', '.. internaltoolsmarker',
be83fd9d46d5 help.merge-tools: do not double document merge tools
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24098
diff changeset
   377
                filemerge.internalsdoc)
30769
e520f0f4b1cf help: merge revsets.txt into revisions.txt
Martin von Zweigbergk <martinvonz@google.com>
parents: 30610
diff changeset
   378
addtopicsymbols('revisions', '.. predicatesmarker', revset.symbols)
26436
a2291c9c85a1 templatekw: remove dockeywords hack
Yuya Nishihara <yuya@tcha.org>
parents: 26415
diff changeset
   379
addtopicsymbols('templates', '.. keywordsmarker', templatekw.keywords)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   380
addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)
36922
521f6c7e1756 templater: split template functions to new module
Yuya Nishihara <yuya@tcha.org>
parents: 36451
diff changeset
   381
addtopicsymbols('templates', '.. functionsmarker', templatefuncs.funcs)
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   382
addtopicsymbols('hgweb', '.. webcommandsmarker', webcommands.commands,
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   383
                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
   384
32566
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   385
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
   386
          **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
   387
    '''
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
    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
   389
    '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
   390
    '''
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
32143
964c6be36590 py3: make sure opts are passed and used correctly in help command
Pulkit Goyal <7895pulkit@gmail.com>
parents: 32076
diff changeset
   392
    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
   393
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   394
    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
   395
        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
   396
            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
   397
                                             strict=unknowncmd)
25660
328739ea70c3 global: mass rewrite to use modern exception syntax
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24871
diff changeset
   398
        except error.AmbiguousCommand as inst:
40263
8cf459d8b111 py3: use py3 as the test tag, dropping the k
Martijn Pieters <mj@octobus.net>
parents: 39614
diff changeset
   399
            # py3 fix: except vars can't be used outside the scope of the
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
            # 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
   401
            prefix = inst.args[0]
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   402
            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
   403
            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
   404
            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
   405
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   406
        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
   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
        # 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
   409
        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
   410
            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
   411
            if entry[0].unknowncmd:
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   412
                try:
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   413
                    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
   414
                except error.UnknownCommand:
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   415
                    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
   416
            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
   417
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   418
        # 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
   419
        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
   420
            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
   421
                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
   422
            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
   423
                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
   424
        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
   425
            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
   426
        # 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
   427
        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
   428
            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
   429
        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
   430
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
        # description
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   432
        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
   433
        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
   434
            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
   435
        if util.safehasattr(entry[0], 'definition'):  # aliased command
28828
3640c1702c43 help: report source of aliases
timeless <timeless@mozdev.org>
parents: 28523
diff changeset
   436
            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
   437
            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
   438
                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
   439
                       (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
   440
            else:
28828
3640c1702c43 help: report source of aliases
timeless <timeless@mozdev.org>
parents: 28523
diff changeset
   441
                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
   442
                       (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
   443
        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
   444
        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
   445
            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
   446
        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
   447
            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
   448
        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
   449
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
        # 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
   451
        # 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
   452
        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
   453
            mod = extensions.find(name)
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   454
            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
   455
            if '\n' in doc.strip():
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   456
                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
   457
                        "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
   458
                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
   459
        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
   460
            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
   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
        # 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
   463
        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
   464
            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
   465
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:
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   467
            rst.append(optrst(_("global options"),
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   468
                              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
   469
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
        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
   471
            if not full:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   472
                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
   473
                           % 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
   474
            elif not ui.quiet:
22110
26f7c8033bed help: tweak --verbose command help hint
Matt Mackall <mpm@selenic.com>
parents: 21796
diff changeset
   475
                rst.append(_('\n(some details hidden, use --verbose '
26f7c8033bed help: tweak --verbose command help hint
Matt Mackall <mpm@selenic.com>
parents: 21796
diff changeset
   476
                               '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
   477
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
        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
   479
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   480
    def helplist(select=None, **opts):
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   481
        # Category -> list of commands
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   482
        cats = {}
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   483
        # Command -> short description
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
   484
        h = {}
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   485
        # Command -> string showing synonyms
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   486
        syns = {}
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
   487
        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
   488
            fs = cmdutil.parsealiases(c)
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   489
            f = fs[0]
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   490
            syns[f] = ', '.join(fs)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   491
            func = e[0]
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   492
            p = ''
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   493
            if c.startswith("^"):
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   494
                p = '^'
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   495
            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
   496
                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
   497
            if (not select and name != 'shortlist' and
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   498
                func.__module__ != commands.__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
   499
                continue
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   500
            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
   501
                continue
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   502
            doc = pycompat.getdoc(func)
27323
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   503
            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
   504
                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
   505
            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
   506
            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
   507
                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
   508
            h[f] = doc.splitlines()[0].rstrip()
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   509
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   510
            cat = getattr(func, 'helpcategory', None) or (
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   511
                registrar.command.CATEGORY_NONE)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   512
            cats.setdefault(cat, []).append(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
   513
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   514
        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
   515
        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
   516
            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
   517
                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
   518
            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
   519
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   520
        # Output top header.
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
   521
        if not ui.quiet:
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   522
            if name == "shortlist":
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   523
                rst.append(_('basic commands:\n\n'))
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   524
            elif name == "debug":
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   525
                rst.append(_('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
   526
            else:
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   527
                rst.append(_('list of commands:\n'))
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   528
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   529
        def appendcmds(cmds):
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   530
            cmds = sorted(cmds)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   531
            for c in cmds:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   532
                if ui.verbose:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   533
                    rst.append(" :%s: %s\n" % (syns[c], h[c]))
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   534
                else:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   535
                    rst.append(' :%s: %s\n' % (c, h[c]))
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   536
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   537
        if name in ('shortlist', 'debug'):
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   538
            # List without categories.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   539
            appendcmds(h)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   540
        else:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   541
            # Check that all categories have an order.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   542
            missing_order = set(cats.keys()) - set(CATEGORY_ORDER)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   543
            if missing_order:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   544
                ui.develwarn('help categories missing from CATEGORY_ORDER: %s' %
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   545
                             missing_order)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   546
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   547
            # List per category.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   548
            for cat in CATEGORY_ORDER:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   549
                catfns = cats.get(cat, [])
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   550
                if catfns:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   551
                    if len(cats) > 1:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   552
                        catname = gettext(CATEGORY_NAMES[cat])
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   553
                        rst.append("\n%s:\n" % catname)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   554
                    rst.append("\n")
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   555
                    appendcmds(catfns)
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
   556
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   557
        ex = opts.get
35356
7f410793c04d py3: handle keyword arguments correctly in help.py
Pulkit Goyal <7895pulkit@gmail.com>
parents: 35045
diff changeset
   558
        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
   559
        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
   560
            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
   561
            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
   562
                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
   563
                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
   564
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   565
            rst.append(_("\nadditional help topics:\n"))
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   566
            # Group commands by category.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   567
            topiccats = {}
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   568
            for topic in helptable:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   569
                names, header, doc = topic[0:3]
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   570
                if len(topic) > 3 and topic[3]:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   571
                    category = topic[3]
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   572
                else:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   573
                    category = TOPIC_CATEGORY_NONE
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   574
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   575
                topiccats.setdefault(category, []).append((names[0], header))
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   576
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   577
            # Check that all categories have an order.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   578
            missing_order = set(topiccats.keys()) - set(TOPIC_CATEGORY_ORDER)
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   579
            if missing_order:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   580
                ui.develwarn(
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   581
                    'help categories missing from TOPIC_CATEGORY_ORDER: %s' %
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   582
                    missing_order)
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   583
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   584
            # Output topics per category.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   585
            for cat in TOPIC_CATEGORY_ORDER:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   586
                topics = topiccats.get(cat, [])
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   587
                if topics:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   588
                    if len(topiccats) > 1:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   589
                        catname = gettext(TOPIC_CATEGORY_NAMES[cat])
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   590
                        rst.append("\n%s:\n" % catname)
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   591
                    rst.append("\n")
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   592
                    for t, desc in topics:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   593
                        rst.append(" :%s: %s\n" % (t, desc))
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
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   595
        if ui.quiet:
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   596
            pass
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   597
        elif ui.verbose:
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   598
            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
   599
                                         commands.globalopts, ui.verbose))
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   600
            if name == 'shortlist':
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   601
                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
   602
                             "of commands)\n"))
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   603
        else:
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   604
            if name == 'shortlist':
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   605
                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
   606
                             "or 'hg -v' for details)\n"))
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   607
            elif name and not full:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   608
                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
   609
                             "text)\n") % name)
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   610
            elif name and syns and name in syns.keys():
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   611
                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
   612
                             "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
   613
            else:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   614
                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
   615
                             "and global options)\n")
22118
9a299c39de01 help: normalize helplist hints
Matt Mackall <mpm@selenic.com>
parents: 22117
diff changeset
   616
                           % (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
   617
        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
   618
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   619
    def helptopic(name, subtopic=None):
27379
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   620
        # Look for sub-topic entry first.
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   621
        header, doc = None, None
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   622
        if subtopic and name in subtopics:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   623
            for names, header, doc in subtopics[name]:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   624
                if subtopic in names:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   625
                    break
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   626
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   627
        if not header:
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   628
            for topic in helptable:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   629
                names, header, doc = topic[0:3]
27379
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   630
                if name in names:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   631
                    break
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   632
            else:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   633
                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
   634
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 18746
diff changeset
   635
        rst = [minirst.section(header)]
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 18746
diff changeset
   636
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
   637
        # 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
   638
        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
   639
            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
   640
        if callable(doc):
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   641
            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
   642
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
        if not ui.verbose:
22114
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   644
            omitted = _('(some details hidden, use --verbose'
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   645
                         ' 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
   646
            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
   647
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
        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
   649
            cmdutil.findcmd(name, commands.table)
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   650
            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
   651
                       "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
   652
        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
   653
            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
   654
        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
   655
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   656
    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
   657
        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
   658
            mod = extensions.find(name)
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   659
            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
   660
        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
   661
            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
   662
            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
   663
            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
   664
                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
   665
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   666
        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
   667
            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
   668
        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
   669
            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
   670
        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
   671
        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
   672
            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
   673
            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
   674
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   675
        if not ui.verbose:
22114
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   676
            omitted = _('(some details hidden, use --verbose'
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   677
                         ' 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
   678
            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
   679
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   680
        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
   681
            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
   682
                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
   683
            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
   684
                ct = {}
26845
7a77ee434179 help: replace some str.split() calls by str.partition() or str.rpartition()
Anton Shestakov <av6@dwimlabs.net>
parents: 26587
diff changeset
   685
            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
   686
            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
   687
        else:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   688
            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
   689
                       " 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
   690
        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
   691
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   692
    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
   693
        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
   694
                                               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
   695
        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
   696
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   697
        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
   698
                              "extension:") % cmd, {ext: doc}, indent=4,
ac27b1b3be85 help: make help deprecated mention the extension
timeless <timeless@mozdev.org>
parents: 27151
diff changeset
   699
                       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
   700
        rst.append('\n')
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   701
        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
   702
                   "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
   703
        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
   704
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   705
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   706
    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
   707
    kw = opts.get('keyword')
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   708
    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
   709
        matches = topicmatch(ui, commands, name or '')
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   710
        helpareas = []
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   711
        if opts.get('extension'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   712
            helpareas += [('extensions', _('Extensions'))]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   713
        if opts.get('command'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   714
            helpareas += [('commands', _('Commands'))]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   715
        if not helpareas:
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   716
            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
   717
                         ('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
   718
                         ('extensions', _('Extensions')),
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   719
                         ('extensioncommands', _('Extension Commands'))]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   720
        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
   721
            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
   722
                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
   723
                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
   724
                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
   725
        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
   726
            msg = _('no matches')
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   727
            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
   728
            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
   729
    elif name and name != 'shortlist':
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   730
        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
   731
        if unknowncmd:
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   732
            queries += [helpextcmd]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   733
        if opts.get('extension'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   734
            queries += [helpext]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   735
        if opts.get('command'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   736
            queries += [helpcmd]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   737
        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
   738
            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
   739
        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
   740
            try:
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   741
                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
   742
                break
21289
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   743
            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
   744
                pass
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   745
        else:
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   746
            if unknowncmd:
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   747
                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
   748
            else:
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   749
                msg = _('no such help topic: %s') % name
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   750
                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
   751
                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
   752
    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
   753
        # 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
   754
        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
   755
            rst = [_("Mercurial Distributed SCM\n"), '\n']
32547
0cec8ad579d4 help: convert dict to strkwargs
Augie Fackler <raf@durin42.com>
parents: 32291
diff changeset
   756
        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
   757
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   758
    return ''.join(rst)
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   759
39339
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   760
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
   761
                  full=True, **opts):
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   762
    """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
   763
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   764
    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
   765
    """
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   766
    if keep is None:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   767
        keep = []
31265
79715ba22f9c help: avoid mutating passed-in `keep` list in `formattedhelp`
Augie Fackler <augie@google.com>
parents: 31129
diff changeset
   768
    else:
79715ba22f9c help: avoid mutating passed-in `keep` list in `formattedhelp`
Augie Fackler <augie@google.com>
parents: 31129
diff changeset
   769
        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
   770
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   771
    # <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
   772
    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
   773
    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
   774
        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
   775
        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
   776
        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
   777
            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
   778
        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
   779
            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
   780
33499
0407a51b9d8c codemod: register core configitems using a script
Jun Wu <quark@fb.com>
parents: 32619
diff changeset
   781
    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
   782
    termwidth = ui.termwidth() - 2
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   783
    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
   784
        textwidth = termwidth
32566
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   785
    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
   786
                 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
   787
39308
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   788
    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
   789
    if 'verbose' in pruned:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   790
        keep.append('omitted')
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   791
    else:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   792
        keep.append('notomitted')
39308
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   793
    blocks, pruned = minirst.parse(text, keep=keep)
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   794
    if section:
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   795
        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
   796
0a766cb1092a help: reorder section filtering flow to not format help text twice
Yuya Nishihara <yuya@tcha.org>
parents: 39308
diff changeset
   797
    # 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
   798
    # 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
   799
    # 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
   800
    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
   801
        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
   802
39308
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   803
    return minirst.formatplain(blocks, textwidth)