mercurial/help.py
author Valentin Gatien-Baron <valentin.gatienbaron@gmail.com>
Tue, 02 Jul 2019 12:59:58 -0400
changeset 42621 99ebde4fec99
parent 42450 9d31581cc44e
child 43076 2372284d9457
permissions -rw-r--r--
commit: improve the files field of changelog for merges Currently, the files list of merge commits repeats all the deletions (either actual deletions, or files that got renamed) that happened between base and p2 of the merge. If p2 is the main branch, the list can easily be much bigger than the change being merged. This results in various problems worth improving: - changelog is bigger than necessary - `hg log directory` lists many unrelated merge commits, and `hg log -v -r commit` frequently fills multiple screens worth of files - it possibly slows down adjustlinkrev, by forcing it to read more manifests, and that function can certainly be a bottleneck - the server side of pulls can waste a lot of time simply opening the filelogs for pointless files (the constant factors for opening even a tiny filelog is apparently pretty bad) So stop listing such files as described in the code. Impacted merge commits and their descendants get a different hash than they would have without this. This doesn't seem problematic, except for convert. The previous commit helped with that in the hg->hg case (but if you do svn->hg twice from scratch, hashes can still change). The rest of the description is numbers. I don't have much to report, because recreating the files list of existing repositories is not easy: - debugupgradeformat and bundle/unbundle don't recreate the list - export/import tends to choke quickly applying patches or on description that contain diffs, - merge commits from the convert extension don't have the right files list for reasons orthogonal to the current commit - replaying the merge with hg update/hg merge/hg revert --all/hg commit can end up failing in hg revert - I wasn't sure that using debugsetparents + debugrebuilddirstate would really build the right thing I measured commit time before and after this change, in a case with no files filtered out, several files filtered out (no difference) and 5k files filtered out (+1% time). Recreating the 100 more recent merges in a private repo, the concatenated uncompressed files lists goes from 1.12MB to 0.52MB. Excluding 3 merges that are not representative, then the size goes from 570k to 15k. I converted part of mozilla-central, and observed file list shrinking quite a bit too, starting at the very first merge, 733641d9feaf, going from 550 files to 10 files (although they have relatively few merges, so they probably wouldn't care). Differential Revision: https://phab.mercurial-scm.org/D6613
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
40421
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
    12
import re
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    13
import textwrap
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    14
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    15
from .i18n import (
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    16
    _,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    17
    gettext,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    18
)
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    19
from . import (
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    20
    cmdutil,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    21
    encoding,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    22
    error,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    23
    extensions,
37091
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
    24
    fancyopts,
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    25
    filemerge,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    26
    fileset,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    27
    minirst,
32143
964c6be36590 py3: make sure opts are passed and used correctly in help command
Pulkit Goyal <7895pulkit@gmail.com>
parents: 32076
diff changeset
    28
    pycompat,
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    29
    registrar,
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    30
    revset,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    31
    templatefilters,
36922
521f6c7e1756 templater: split template functions to new module
Yuya Nishihara <yuya@tcha.org>
parents: 36451
diff changeset
    32
    templatefuncs,
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    33
    templatekw,
40421
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
    34
    ui as uimod,
27479
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    35
    util,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    36
)
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    37
from .hgweb import (
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    38
    webcommands,
3ce1d50daa99 help: use absolute_import
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27400
diff changeset
    39
)
42041
3e47d1ec9da5 util: extract compression code in `mercurial.utils.compression`
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 41075
diff changeset
    40
from .utils import (
3e47d1ec9da5 util: extract compression code in `mercurial.utils.compression`
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 41075
diff changeset
    41
    compression,
3e47d1ec9da5 util: extract compression code in `mercurial.utils.compression`
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 41075
diff changeset
    42
)
8863
7b19c3c0172b help: adding a new help topic about extensions
Cédric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
    43
32291
bd872f64a8ba cleanup: use set literals
Martin von Zweigbergk <martinvonz@google.com>
parents: 32143
diff changeset
    44
_exclkeywords = {
31080
6918c9215201 help: hide command line options marked as "advanced"
Jun Wu <quark@fb.com>
parents: 31061
diff changeset
    45
    "(ADVANCED)",
26370
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
    "(EXPERIMENTAL)",
31080
6918c9215201 help: hide command line options marked as "advanced"
Jun Wu <quark@fb.com>
parents: 31061
diff changeset
    48
    # 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
    49
    _("(ADVANCED)"),
26370
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    50
    # 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
    51
    _("(DEPRECATED)"),
44cc9f63a2f1 help: include parens in DEPRECATED/EXPERIMENTAL keywords
Yuya Nishihara <yuya@tcha.org>
parents: 26369
diff changeset
    52
    # 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
    53
    _("(EXPERIMENTAL)"),
32291
bd872f64a8ba cleanup: use set literals
Martin von Zweigbergk <martinvonz@google.com>
parents: 32143
diff changeset
    54
}
26369
4799b5c4aaf4 help: define list of keywords that should be excluded from non-verbose output
Yuya Nishihara <yuya@tcha.org>
parents: 26238
diff changeset
    55
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    56
# The order in which command categories will be displayed.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    57
# Extensions with custom categories should insert them into this list
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    58
# 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
    59
# assuming absolute positions.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    60
CATEGORY_ORDER = [
40293
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    61
    registrar.command.CATEGORY_REPO_CREATION,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    62
    registrar.command.CATEGORY_REMOTE_REPO_MANAGEMENT,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    63
    registrar.command.CATEGORY_COMMITTING,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    64
    registrar.command.CATEGORY_CHANGE_MANAGEMENT,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    65
    registrar.command.CATEGORY_CHANGE_ORGANIZATION,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    66
    registrar.command.CATEGORY_FILE_CONTENTS,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    67
    registrar.command.CATEGORY_CHANGE_NAVIGATION ,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    68
    registrar.command.CATEGORY_WORKING_DIRECTORY,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    69
    registrar.command.CATEGORY_IMPORT_EXPORT,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    70
    registrar.command.CATEGORY_MAINTENANCE,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    71
    registrar.command.CATEGORY_HELP,
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    72
    registrar.command.CATEGORY_MISC,
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    73
    registrar.command.CATEGORY_NONE,
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    74
]
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    75
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    76
# Human-readable category names. These are translated.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    77
# Extensions with custom categories should add their names here.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    78
CATEGORY_NAMES = {
40293
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    79
    registrar.command.CATEGORY_REPO_CREATION: 'Repository creation',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    80
    registrar.command.CATEGORY_REMOTE_REPO_MANAGEMENT:
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    81
        'Remote repository management',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    82
    registrar.command.CATEGORY_COMMITTING: 'Change creation',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    83
    registrar.command.CATEGORY_CHANGE_NAVIGATION: 'Change navigation',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    84
    registrar.command.CATEGORY_CHANGE_MANAGEMENT: 'Change manipulation',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    85
    registrar.command.CATEGORY_CHANGE_ORGANIZATION: 'Change organization',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    86
    registrar.command.CATEGORY_WORKING_DIRECTORY:
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    87
        'Working directory management',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    88
    registrar.command.CATEGORY_FILE_CONTENTS: 'File content management',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    89
    registrar.command.CATEGORY_IMPORT_EXPORT: 'Change import/export',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    90
    registrar.command.CATEGORY_MAINTENANCE: 'Repository maintenance',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    91
    registrar.command.CATEGORY_HELP: 'Help',
c303d65d2e34 help: assigning categories to existing commands
rdamazio@google.com
parents: 40292
diff changeset
    92
    registrar.command.CATEGORY_MISC: 'Miscellaneous commands',
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    93
    registrar.command.CATEGORY_NONE: 'Uncategorized commands',
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    94
}
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
    95
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
    96
# Topic categories.
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
    97
TOPIC_CATEGORY_IDS = 'ids'
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
    98
TOPIC_CATEGORY_OUTPUT = 'output'
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
    99
TOPIC_CATEGORY_CONFIG = 'config'
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   100
TOPIC_CATEGORY_CONCEPTS = 'concepts'
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   101
TOPIC_CATEGORY_MISC = 'misc'
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   102
TOPIC_CATEGORY_NONE = 'none'
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   103
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   104
# 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
   105
# 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
   106
# 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
   107
# assuming absolute positions.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   108
TOPIC_CATEGORY_ORDER = [
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   109
    TOPIC_CATEGORY_IDS,
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   110
    TOPIC_CATEGORY_OUTPUT,
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   111
    TOPIC_CATEGORY_CONFIG,
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   112
    TOPIC_CATEGORY_CONCEPTS,
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   113
    TOPIC_CATEGORY_MISC,
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   114
    TOPIC_CATEGORY_NONE,
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   115
]
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   116
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   117
# Human-readable topic category names. These are translated.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   118
TOPIC_CATEGORY_NAMES = {
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   119
    TOPIC_CATEGORY_IDS: 'Mercurial identifiers',
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   120
    TOPIC_CATEGORY_OUTPUT: 'Mercurial output',
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   121
    TOPIC_CATEGORY_CONFIG: 'Mercurial configuration',
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   122
    TOPIC_CATEGORY_CONCEPTS: 'Concepts',
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   123
    TOPIC_CATEGORY_MISC: 'Miscellaneous',
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   124
    TOPIC_CATEGORY_NONE: 'Uncategorized topics',
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   125
}
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   126
20582
02c303f64917 help: exclude deprecated extensions in the disabled part of 'help extensions'
Augie Fackler <raf@durin42.com>
parents: 20034
diff changeset
   127
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
   128
    '''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
   129
    rst = []
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
   130
    if exts:
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
   131
        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
   132
            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
   133
                continue
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
   134
            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
   135
    if rst:
7625f6387fc4 help: make listexts less confusing for deprecated exts
timeless <timeless@mozdev.org>
parents: 26845
diff changeset
   136
        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
   137
    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
   138
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   139
def extshelp(ui):
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   140
    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
   141
    rst.extend(listexts(
02c303f64917 help: exclude deprecated extensions in the disabled part of 'help extensions'
Augie Fackler <raf@durin42.com>
parents: 20034
diff changeset
   142
        _('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
   143
    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
   144
                        showdeprecated=ui.verbose))
16852
af69b2b64d6e help: format extension lists using RST
Olav Reinert <seroton10@gmail.com>
parents: 16845
diff changeset
   145
    doc = ''.join(rst)
8863
7b19c3c0172b help: adding a new help topic about extensions
Cédric Duval <cedricduval@free.fr>
parents: 8668
diff changeset
   146
    return doc
7013
f56e788fa292 i18n: mark help strings for translation
Martin Geisler <mg@daimi.au.dk>
parents: 7012
diff changeset
   147
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   148
def optrst(header, options, verbose):
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   149
    data = []
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   150
    multioccur = False
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   151
    for option in options:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   152
        if len(option) == 5:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   153
            shortopt, longopt, default, desc, optlabel = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   154
        else:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   155
            shortopt, longopt, default, desc = option
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   156
            optlabel = _("VALUE") # default label
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   157
26369
4799b5c4aaf4 help: define list of keywords that should be excluded from non-verbose output
Yuya Nishihara <yuya@tcha.org>
parents: 26238
diff changeset
   158
        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
   159
            continue
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
        so = ''
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   162
        if shortopt:
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   163
            so = '-' + shortopt
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   164
        lo = '--' + longopt
41009
fcc0a7ac9ebd help: show "[no-]" only for default-on Flags
Martin von Zweigbergk <martinvonz@google.com>
parents: 40955
diff changeset
   165
        if default is True:
40955
f6187e60f792 help: present boolean arguments as "--[no-]foo"
Martin von Zweigbergk <martinvonz@google.com>
parents: 40954
diff changeset
   166
            lo = '--[no-]' + longopt
37091
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
   167
979c8ce9022d fancyopts: fix rendering of customopt defaults in help text
Daniel Ploch <dploch@google.com>
parents: 36922
diff changeset
   168
        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
   169
            default = default.getdefaultvalue()
41010
e8e2a7656e83 help: hide default value for default-off flags
Martin von Zweigbergk <martinvonz@google.com>
parents: 41009
diff changeset
   170
        if default and not callable(default):
32619
d110fb58424c help: convert flag default to bytes portably
Augie Fackler <raf@durin42.com>
parents: 32615
diff changeset
   171
            # 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
   172
            # 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
   173
            # 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
   174
            # then convert it to bytes.
40953
05abb5fb146a help: use "default: on" instead of "default: True"
Martin von Zweigbergk <martinvonz@google.com>
parents: 40595
diff changeset
   175
            defaultstr = pycompat.bytestr(default)
41010
e8e2a7656e83 help: hide default value for default-off flags
Martin von Zweigbergk <martinvonz@google.com>
parents: 41009
diff changeset
   176
            if default is True:
e8e2a7656e83 help: hide default value for default-off flags
Martin von Zweigbergk <martinvonz@google.com>
parents: 41009
diff changeset
   177
                defaultstr = _("on")
40953
05abb5fb146a help: use "default: on" instead of "default: True"
Martin von Zweigbergk <martinvonz@google.com>
parents: 40595
diff changeset
   178
            desc += _(" (default: %s)") % defaultstr
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   179
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   180
        if isinstance(default, list):
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   181
            lo += " %s [+]" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   182
            multioccur = True
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   183
        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
   184
            lo += " %s" % optlabel
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   185
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   186
        data.append((so, lo, desc))
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   187
22117
c1d93edcf004 help: fold repeatable option message into option table header
Matt Mackall <mpm@selenic.com>
parents: 22116
diff changeset
   188
    if multioccur:
c1d93edcf004 help: fold repeatable option message into option table header
Matt Mackall <mpm@selenic.com>
parents: 22116
diff changeset
   189
        header += (_(" ([+] can be repeated)"))
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   190
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   191
    rst = ['\n%s:\n\n' % header]
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   192
    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
   193
16815
e740746ea557 minirst: generate tables as a list of joined lines
Olav Reinert <seroton10@gmail.com>
parents: 16781
diff changeset
   194
    return ''.join(rst)
16781
c0b98f436cce help: move some helper functions to help.py
Olav Reinert <seroton10@gmail.com>
parents: 16711
diff changeset
   195
17837
b623e323c561 help: indicate help omitting if help document is not fully displayed
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17323
diff changeset
   196
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
   197
    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
   198
    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
   199
        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
   200
40414
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   201
def filtercmd(ui, cmd, func, kw, doc):
27323
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   202
    if not ui.debugflag and cmd.startswith("debug") and kw != "debug":
40414
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   203
        # Debug command, and user is not looking for those.
27323
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   204
        return True
40414
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   205
    if not ui.verbose:
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   206
        if not kw and not doc:
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   207
            # Command had no documentation, no point in showing it by default.
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   208
            return True
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   209
        if getattr(func, 'alias', False) and not getattr(func, 'owndoc', False):
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   210
            # Alias didn't have its own documentation.
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   211
            return True
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   212
        if doc and any(w in doc for w in _exclkeywords):
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   213
            # Documentation has excluded keywords.
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   214
            return True
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   215
    if kw == "shortlist" and not getattr(func, 'helpbasic', False):
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   216
        # We're presenting the short list but the command is not basic.
27323
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   217
        return True
40412
ab09e797fbed help: allow commands to be hidden
rdamazio@google.com
parents: 40295
diff changeset
   218
    if ui.configbool('help', 'hidden-command.%s' % cmd):
40414
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   219
        # Configuration explicitly hides the command.
27323
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   220
        return True
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   221
    return False
0fe93498ef07 help: refactor filtercmd
timeless <timeless@mozdev.org>
parents: 27152
diff changeset
   222
40413
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   223
def filtertopic(ui, topic):
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   224
    return ui.configbool('help', 'hidden-topic.%s' % topic, False)
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   225
32566
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   226
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
   227
    """Return help topics matching kw.
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   228
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   229
    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
   230
    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
   231
    """
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   232
    kw = encoding.lower(kw)
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   233
    def lowercontains(container):
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   234
        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
   235
    results = {'topics': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   236
               'commands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   237
               'extensions': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   238
               'extensioncommands': [],
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   239
               }
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   240
    for topic in helptable:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   241
        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
   242
        # 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
   243
        if (sum(map(lowercontains, names))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   244
            or lowercontains(header)
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   245
            or (callable(doc) and lowercontains(doc(ui)))):
40413
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   246
            name = names[0]
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   247
            if not filtertopic(ui, name):
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   248
                results['topics'].append((names[0], header))
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   249
    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
   250
        if len(entry) == 3:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   251
            summary = entry[2]
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   252
        else:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   253
            summary = ''
16845
4594729c61ee help: fix search with `-k` option in non-ASCII locales
Nikolaj Sjujskij <sterkrig@myopera.com>
parents: 16816
diff changeset
   254
        # translate docs *before* searching there
40414
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   255
        func = entry[0]
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   256
        docs = _(pycompat.getdoc(func)) or ''
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   257
        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
   258
            doclines = docs.splitlines()
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   259
            if doclines:
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   260
                summary = doclines[0]
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   261
            cmdname = cmdutil.parsealiases(cmd)[0]
40414
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   262
            if filtercmd(ui, cmdname, func, kw, docs):
27324
5456374561a7 help: call filtercmd from topicmatch
timeless <timeless@mozdev.org>
parents: 27323
diff changeset
   263
                continue
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   264
            results['commands'].append((cmdname, summary))
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   265
    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
   266
        extensions.enabled(False).iteritems(),
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   267
        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
   268
        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
   269
            continue
26845
7a77ee434179 help: replace some str.split() calls by str.partition() or str.rpartition()
Anton Shestakov <av6@dwimlabs.net>
parents: 26587
diff changeset
   270
        name = name.rpartition('.')[-1]
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   271
        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
   272
            # 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
   273
            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
   274
        try:
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   275
            mod = extensions.load(ui, name, '')
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   276
        except ImportError:
1e2454b60e59 help: do not abort topicmatch() because of unimportable extensions
Yuya Nishihara <yuya@tcha.org>
parents: 33499
diff changeset
   277
            # 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
   278
            continue
16710
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   279
        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
   280
            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
   281
                cmdname = cmdutil.parsealiases(cmd)[0]
40414
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   282
                func = entry[0]
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   283
                cmddoc = pycompat.getdoc(func)
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   284
                if cmddoc:
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   285
                    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
   286
                else:
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
   287
                    cmddoc = _('(no help text available)')
40414
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   288
                if filtercmd(ui, cmdname, func, kw, cmddoc):
27387
dfab0afde928 help: filter extension commands
timeless <timeless@mozdev.org>
parents: 27379
diff changeset
   289
                    continue
16884
4fd1f1d7569b help: fix 'hg help -k' matching an extension without docs
Thomas Arendsen Hein <thomas@intevation.de>
parents: 16855
diff changeset
   290
                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
   291
    return results
a17983680f12 help: introduce topicmatch for finding topics matching a keyword
Augie Fackler <raf@durin42.com>
parents: 16568
diff changeset
   292
27375
c4a062d090ee help: teach loaddoc to load from a different directory
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27325
diff changeset
   293
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
   294
    """Return a delayed loader for help/topic.txt."""
3798
6f0c42d50394 move environment topic
Matt Mackall <mpm@selenic.com>
parents: 3795
diff changeset
   295
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   296
    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
   297
        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
   298
        if subdir:
c4a062d090ee help: teach loaddoc to load from a different directory
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27325
diff changeset
   299
            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
   300
        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
   301
        doc = gettext(util.readfile(path))
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   302
        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
   303
            doc = rewriter(ui, topic, doc)
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   304
        return doc
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   305
9539
c904e76e3834 help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents: 9536
diff changeset
   306
    return loader
7677
6a0bc2dc9da6 help: add a topic about some of the templating features
Alexander Solovyov <piranha@piranha.org.ua>
parents: 7387
diff changeset
   307
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   308
internalstable = sorted([
36451
1fa35ca345a5 internals: document bundle2 format
Gregory Szorc <gregory.szorc@gmail.com>
parents: 36250
diff changeset
   309
    (['bundle2'], _('Bundle2'),
1fa35ca345a5 internals: document bundle2 format
Gregory Szorc <gregory.szorc@gmail.com>
parents: 36250
diff changeset
   310
     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
   311
    (['bundles'], _('Bundles'),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   312
     loaddoc('bundles', subdir='internals')),
39409
2fe21c65777e internals: document CBOR utilization
Gregory Szorc <gregory.szorc@gmail.com>
parents: 39339
diff changeset
   313
    (['cbor'], _('CBOR'),
2fe21c65777e internals: document CBOR utilization
Gregory Szorc <gregory.szorc@gmail.com>
parents: 39339
diff changeset
   314
     loaddoc('cbor', subdir='internals')),
31293
2cdb1239ff8c help: update help.internalstable for new censor docs
Augie Fackler <augie@google.com>
parents: 31265
diff changeset
   315
    (['censor'], _('Censor'),
2cdb1239ff8c help: update help.internalstable for new censor docs
Augie Fackler <augie@google.com>
parents: 31265
diff changeset
   316
     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
   317
    (['changegroups'], _('Changegroups'),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   318
     loaddoc('changegroups', subdir='internals')),
34951
fb7f58daca48 internals: copy-edit "register" -> "registrar" in configitem docs
Kevin Bullock <kbullock+mercurial@ringworld.org>
parents: 34932
diff changeset
   319
    (['config'], _('Config Registrar'),
34932
fd78276948b4 internal-doc: document the config register mechanism
Boris Feld <boris.feld@octobus.net>
parents: 34912
diff changeset
   320
     loaddoc('config', subdir='internals')),
40595
419d703115b0 help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents: 40460
diff changeset
   321
    (['extensions', 'extension'], _('Extension API'),
419d703115b0 help: add internals.extensions topic
Yuya Nishihara <yuya@tcha.org>
parents: 40460
diff changeset
   322
     loaddoc('extensions', subdir='internals')),
42450
9d31581cc44e help: add help entry for internals.mergestate
Navaneeth Suresh <navaneeths1998@gmail.com>
parents: 42394
diff changeset
   323
    (['mergestate'], _('Mergestate'),
9d31581cc44e help: add help entry for internals.mergestate
Navaneeth Suresh <navaneeths1998@gmail.com>
parents: 42394
diff changeset
   324
     loaddoc('mergestate', 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
   325
    (['requirements'], _('Repository Requirements'),
28523
045fe7042510 help: document requirements
Gregory Szorc <gregory.szorc@gmail.com>
parents: 28058
diff changeset
   326
     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
   327
    (['revlogs'], _('Revision Logs'),
27631
c18292a6ff54 internals: document revlog format
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27479
diff changeset
   328
     loaddoc('revlogs', subdir='internals')),
29859
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29747
diff changeset
   329
    (['wireprotocol'], _('Wire Protocol'),
a1092e2d70a3 help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents: 29747
diff changeset
   330
     loaddoc('wireprotocol', subdir='internals')),
39614
a2880ac67ee0 help: add internals.wireprotocolrpc to the table
Yuya Nishihara <yuya@tcha.org>
parents: 39461
diff changeset
   331
    (['wireprotocolrpc'], _('Wire Protocol RPC'),
a2880ac67ee0 help: add internals.wireprotocolrpc to the table
Yuya Nishihara <yuya@tcha.org>
parents: 39461
diff changeset
   332
     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
   333
    (['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
   334
     loaddoc('wireprotocolv2', subdir='internals')),
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   335
])
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   336
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   337
def internalshelp(ui):
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   338
    """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
   339
    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
   340
             '\n']
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   341
    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
   342
        lines.append(' :%s: %s\n' % (names[0], header))
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   343
27400
64208bd4c580 help: add missed last new line to "internals" topic
Yuya Nishihara <yuya@tcha.org>
parents: 27387
diff changeset
   344
    return ''.join(lines)
27376
fc810d950278 help: add "internals" topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27375
diff changeset
   345
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
   346
helptable = sorted([
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   347
    (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   348
     TOPIC_CATEGORY_CONCEPTS),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   349
    (['color'], _("Colorizing Outputs"), loaddoc('color'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   350
     TOPIC_CATEGORY_OUTPUT),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   351
    (["config", "hgrc"], _("Configuration Files"), loaddoc('config'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   352
     TOPIC_CATEGORY_CONFIG),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   353
    (['deprecated'], _("Deprecated Features"), loaddoc('deprecated'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   354
     TOPIC_CATEGORY_MISC),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   355
    (["dates"], _("Date Formats"), loaddoc('dates'), TOPIC_CATEGORY_OUTPUT),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   356
    (["flags"], _("Command-line flags"), loaddoc('flags'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   357
     TOPIC_CATEGORY_CONFIG),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   358
    (["patterns"], _("File Name Patterns"), loaddoc('patterns'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   359
     TOPIC_CATEGORY_IDS),
10282
08a0f04b56bd many, many trivial check-code fixups
Matt Mackall <mpm@selenic.com>
parents: 10263
diff changeset
   360
    (['environment', 'env'], _('Environment Variables'),
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   361
     loaddoc('environment'), TOPIC_CATEGORY_CONFIG),
30769
e520f0f4b1cf help: merge revsets.txt into revisions.txt
Martin von Zweigbergk <martinvonz@google.com>
parents: 30610
diff changeset
   362
    (['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   363
      _('Specifying Revisions'), loaddoc('revisions'), TOPIC_CATEGORY_IDS),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   364
    (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   365
     TOPIC_CATEGORY_IDS),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   366
    (['diffs'], _('Diff Formats'), loaddoc('diffs'), TOPIC_CATEGORY_OUTPUT),
30812
98bfce9bd5e5 help: make "mergetool" an alias for "merge-tools"
Gregory Szorc <gregory.szorc@gmail.com>
parents: 30769
diff changeset
   367
    (['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'),
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   368
     loaddoc('merge-tools'), TOPIC_CATEGORY_CONFIG),
16568
770190bff625 help: add reference to template help (issue3413)
A. S. Budden <abudden@gmail.com>
parents: 16547
diff changeset
   369
    (['templating', 'templates', 'template', 'style'], _('Template Usage'),
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   370
     loaddoc('templates'), TOPIC_CATEGORY_OUTPUT),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   371
    (['urls'], _('URL Paths'), loaddoc('urls'), TOPIC_CATEGORY_IDS),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   372
    (["extensions"], _("Using Additional Features"), extshelp,
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   373
     TOPIC_CATEGORY_CONFIG),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   374
    (["subrepos", "subrepo"], _("Subrepositories"), loaddoc('subrepos'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   375
     TOPIC_CATEGORY_CONCEPTS),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   376
    (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   377
     TOPIC_CATEGORY_CONFIG),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   378
    (["glossary"], _("Glossary"), loaddoc('glossary'), TOPIC_CATEGORY_CONCEPTS),
17321
f3fd9d6802b7 help: fix helptable indentation
Mads Kiilerich <mads@kiilerich.com>
parents: 17187
diff changeset
   379
    (["hgignore", "ignore"], _("Syntax for Mercurial Ignore Files"),
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   380
     loaddoc('hgignore'), TOPIC_CATEGORY_IDS),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   381
    (["phases"], _("Working with Phases"), loaddoc('phases'),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   382
     TOPIC_CATEGORY_CONCEPTS),
25881
9de443515f1d help: scripting help topic
Gregory Szorc <gregory.szorc@gmail.com>
parents: 25660
diff changeset
   383
    (['scripting'], _('Using Mercurial from scripts and automation'),
40294
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   384
     loaddoc('scripting'), TOPIC_CATEGORY_MISC),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   385
    (['internals'], _("Technical implementation topics"), internalshelp,
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   386
     TOPIC_CATEGORY_MISC),
fabbf9310025 help: assigning topic categories
Rodrigo Damazio <rdamazio@google.com>
parents: 40293
diff changeset
   387
    (['pager'], _("Pager Support"), loaddoc('pager'), TOPIC_CATEGORY_CONFIG),
13888
9e5407a67dea help: sort help topics to make the output more readable (issue2751)
Yun Lee <yunlee.bj@gmail.com>
parents: 13593
diff changeset
   388
])
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   389
27379
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   390
# 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
   391
subtopics = {
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   392
    'internals': internalstable,
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   393
}
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   394
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   395
# 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
   396
# returning the updated version
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   397
helphooks = {}
12820
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   398
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   399
def addtopichook(topic, rewriter):
0edc0aa7432d help: add topic rewriting hooks
Patrick Mezard <pmezard@gmail.com>
parents: 12818
diff changeset
   400
    helphooks.setdefault(topic, []).append(rewriter)
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   401
26414
c44b507e7c78 help: pass around ui to rewriter hooks (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26413
diff changeset
   402
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
   403
    """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
   404
    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
   405
    """
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   406
    entries = []
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   407
    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
   408
        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
   409
        if (not text
46af0adb5c37 help: hide deprecated filesets, revsets and template items if not verbose
Yuya Nishihara <yuya@tcha.org>
parents: 26414
diff changeset
   410
            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
   411
            continue
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   412
        text = gettext(text)
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   413
        if dedent:
32549
633c635a790a help: work around textwrap.dedent() only working on strings
Augie Fackler <raf@durin42.com>
parents: 32547
diff changeset
   414
            # 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
   415
            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
   416
        lines = text.splitlines()
16250
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   417
        doclines = [(lines[0])]
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   418
        for l in lines[1:]:
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   419
            # 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
   420
            if l.strip().startswith('>>>'):
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   421
                break
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   422
            if dedent:
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   423
                doclines.append(l.rstrip())
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   424
            else:
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   425
                doclines.append('  ' + l.strip())
16250
684864d54903 help: strip doctest from dochelp
"Yann E. MORIN" <yann.morin.1998@free.fr>
parents: 16126
diff changeset
   426
        entries.append('\n'.join(doclines))
13593
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   427
    entries = '\n\n'.join(entries)
cc4721ed7a2a help: extract items doc generation function
Patrick Mezard <pmezard@gmail.com>
parents: 12828
diff changeset
   428
    return doc.replace(marker, entries)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   429
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   430
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
   431
    def add(ui, topic, doc):
c44b507e7c78 help: pass around ui to rewriter hooks (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26413
diff changeset
   432
        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
   433
    addtopichook(topic, add)
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   434
31793
69d8fcf20014 help: document bundle specifications
Gregory Szorc <gregory.szorc@gmail.com>
parents: 31293
diff changeset
   435
addtopicsymbols('bundlespec', '.. bundlecompressionmarker',
42041
3e47d1ec9da5 util: extract compression code in `mercurial.utils.compression`
Pierre-Yves David <pierre-yves.david@octobus.net>
parents: 41075
diff changeset
   436
                compression.bundlecompressiontopics())
14686
6ab8b17adc03 fileset: add a help topic
Matt Mackall <mpm@selenic.com>
parents: 14318
diff changeset
   437
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
   438
addtopicsymbols('merge-tools', '.. internaltoolsmarker',
be83fd9d46d5 help.merge-tools: do not double document merge tools
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24098
diff changeset
   439
                filemerge.internalsdoc)
30769
e520f0f4b1cf help: merge revsets.txt into revisions.txt
Martin von Zweigbergk <martinvonz@google.com>
parents: 30610
diff changeset
   440
addtopicsymbols('revisions', '.. predicatesmarker', revset.symbols)
26436
a2291c9c85a1 templatekw: remove dockeywords hack
Yuya Nishihara <yuya@tcha.org>
parents: 26415
diff changeset
   441
addtopicsymbols('templates', '.. keywordsmarker', templatekw.keywords)
14318
1f46be4689ed help: consolidate topic hooks in help.py
Matt Mackall <mpm@selenic.com>
parents: 14317
diff changeset
   442
addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)
36922
521f6c7e1756 templater: split template functions to new module
Yuya Nishihara <yuya@tcha.org>
parents: 36451
diff changeset
   443
addtopicsymbols('templates', '.. functionsmarker', templatefuncs.funcs)
24098
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   444
addtopicsymbols('hgweb', '.. webcommandsmarker', webcommands.commands,
067540702f64 help: teach topic symbols how to dedent
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24080
diff changeset
   445
                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
   446
40421
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   447
def inserttweakrc(ui, topic, doc):
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   448
    marker = '.. tweakdefaultsmarker'
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   449
    repl = uimod.tweakrc
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   450
    def sub(m):
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   451
        lines = [m.group(1) + s for s in repl.splitlines()]
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   452
        return '\n'.join(lines)
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   453
    return re.sub(br'( *)%s' % re.escape(marker), sub, doc)
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   454
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   455
addtopichook('config', inserttweakrc)
e928bedf0919 help: describe what ui.tweakdefaults changes, concretely
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 40295
diff changeset
   456
32566
1b90036f42f0 help: pass commands module by argument
Yuya Nishihara <yuya@tcha.org>
parents: 32549
diff changeset
   457
def help_(ui, commands, name, unknowncmd=False, full=True, subtopic=None,
42394
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   458
          fullname=None, **opts):
18746
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   459
    '''
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
    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
   461
    '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
   462
    '''
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
32143
964c6be36590 py3: make sure opts are passed and used correctly in help command
Pulkit Goyal <7895pulkit@gmail.com>
parents: 32076
diff changeset
   464
    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
   465
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   466
    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
   467
        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
   468
            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
   469
                                             strict=unknowncmd)
25660
328739ea70c3 global: mass rewrite to use modern exception syntax
Gregory Szorc <gregory.szorc@gmail.com>
parents: 24871
diff changeset
   470
        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
   471
            # 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
   472
            # 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
   473
            prefix = inst.args[0]
36250
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   474
            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
   475
            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
   476
            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
   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
        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
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   480
        # 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
   481
        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
   482
            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
   483
            if entry[0].unknowncmd:
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   484
                try:
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   485
                    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
   486
                except error.UnknownCommand:
7ada34676db8 help: provide help of bad alias without executing aliascmd()
Yuya Nishihara <yuya@tcha.org>
parents: 22160
diff changeset
   487
                    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
   488
            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
   489
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   490
        # 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
   491
        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
   492
            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
   493
                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
   494
            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
   495
                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
   496
        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
   497
            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
   498
        # 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
   499
        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
   500
            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
   501
        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
   502
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   503
        # description
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   504
        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
   505
        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
   506
            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
   507
        if util.safehasattr(entry[0], 'definition'):  # aliased command
28828
3640c1702c43 help: report source of aliases
timeless <timeless@mozdev.org>
parents: 28523
diff changeset
   508
            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
   509
            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
   510
                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
   511
                       (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
   512
            else:
28828
3640c1702c43 help: report source of aliases
timeless <timeless@mozdev.org>
parents: 28523
diff changeset
   513
                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
   514
                       (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
   515
        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
   516
        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
   517
            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
   518
        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
   519
            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
   520
        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
   521
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   522
        # 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
   523
        # 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
   524
        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
   525
            mod = extensions.find(name)
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   526
            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
   527
            if '\n' in doc.strip():
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   528
                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
   529
                        "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
   530
                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
   531
        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
   532
            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
   533
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   534
        # 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
   535
        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
   536
            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
   537
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   538
        if ui.verbose:
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   539
            rst.append(optrst(_("global options"),
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   540
                              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
   541
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   542
        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
   543
            if not full:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   544
                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
   545
                           % 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
   546
            elif not ui.quiet:
22110
26f7c8033bed help: tweak --verbose command help hint
Matt Mackall <mpm@selenic.com>
parents: 21796
diff changeset
   547
                rst.append(_('\n(some details hidden, use --verbose '
26f7c8033bed help: tweak --verbose command help hint
Matt Mackall <mpm@selenic.com>
parents: 21796
diff changeset
   548
                               '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
   549
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   550
        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
   551
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   552
    def helplist(select=None, **opts):
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   553
        # Category -> list of commands
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   554
        cats = {}
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   555
        # 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
   556
        h = {}
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   557
        # Command -> string showing synonyms
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   558
        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
   559
        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
   560
            fs = cmdutil.parsealiases(c)
4174970c9147 help: use cmdutil.parsealiases() to resolve command name
Yuya Nishihara <yuya@tcha.org>
parents: 36249
diff changeset
   561
            f = fs[0]
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   562
            syns[f] = ', '.join(fs)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   563
            func = e[0]
40295
fa88170c10bb help: adding a proper declaration for shortlist/basic commands (API)
Rodrigo Damazio <rdamazio@google.com>
parents: 40294
diff changeset
   564
            if select and not select(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
   565
                continue
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   566
            doc = pycompat.getdoc(func)
40414
444861dc1e55 help: displaying documented aliases by default
rdamazio@google.com
parents: 40413
diff changeset
   567
            if filtercmd(ui, f, func, 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
   568
                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
   569
            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
   570
            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
   571
                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
   572
            h[f] = doc.splitlines()[0].rstrip()
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   573
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   574
            cat = getattr(func, 'helpcategory', None) or (
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   575
                registrar.command.CATEGORY_NONE)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   576
            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
   577
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   578
        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
   579
        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
   580
            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
   581
                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
   582
            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
   583
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   584
        # 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
   585
        if not ui.quiet:
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   586
            if name == "shortlist":
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   587
                rst.append(_('basic commands:\n\n'))
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   588
            elif name == "debug":
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   589
                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
   590
            else:
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   591
                rst.append(_('list of commands:\n'))
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   592
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   593
        def appendcmds(cmds):
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   594
            cmds = sorted(cmds)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   595
            for c in cmds:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   596
                if ui.verbose:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   597
                    rst.append(" :%s: %s\n" % (syns[c], h[c]))
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   598
                else:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   599
                    rst.append(' :%s: %s\n' % (c, h[c]))
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   600
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   601
        if name in ('shortlist', 'debug'):
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   602
            # List without categories.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   603
            appendcmds(h)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   604
        else:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   605
            # Check that all categories have an order.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   606
            missing_order = set(cats.keys()) - set(CATEGORY_ORDER)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   607
            if missing_order:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   608
                ui.develwarn('help categories missing from CATEGORY_ORDER: %s' %
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   609
                             missing_order)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   610
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   611
            # List per category.
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   612
            for cat in CATEGORY_ORDER:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   613
                catfns = cats.get(cat, [])
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   614
                if catfns:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   615
                    if len(cats) > 1:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   616
                        catname = gettext(CATEGORY_NAMES[cat])
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   617
                        rst.append("\n%s:\n" % catname)
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   618
                    rst.append("\n")
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   619
                    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
   620
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   621
        ex = opts.get
35356
7f410793c04d py3: handle keyword arguments correctly in help.py
Pulkit Goyal <7895pulkit@gmail.com>
parents: 35045
diff changeset
   622
        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
   623
        if not name and anyopts:
41075
d0c86a7447a6 help: show advanced, experimental and deprecated extensions with --verbose
Matt Harbison <matt_harbison@yahoo.com>
parents: 41074
diff changeset
   624
            exts = listexts(_('enabled extensions:'), extensions.enabled(),
d0c86a7447a6 help: show advanced, experimental and deprecated extensions with --verbose
Matt Harbison <matt_harbison@yahoo.com>
parents: 41074
diff changeset
   625
                            showdeprecated=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
   626
            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
   627
                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
   628
                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
   629
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   630
            rst.append(_("\nadditional help topics:\n"))
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   631
            # Group commands by category.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   632
            topiccats = {}
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   633
            for topic in helptable:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   634
                names, header, doc = topic[0:3]
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   635
                if len(topic) > 3 and topic[3]:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   636
                    category = topic[3]
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   637
                else:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   638
                    category = TOPIC_CATEGORY_NONE
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   639
40413
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   640
                topicname = names[0]
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   641
                if not filtertopic(ui, topicname):
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   642
                    topiccats.setdefault(category, []).append(
1ddd202c47d9 help: allow hiding of help topics
rdamazio@google.com
parents: 40412
diff changeset
   643
                        (topicname, header))
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   644
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   645
            # Check that all categories have an order.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   646
            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
   647
            if missing_order:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   648
                ui.develwarn(
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   649
                    'help categories missing from TOPIC_CATEGORY_ORDER: %s' %
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   650
                    missing_order)
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   651
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   652
            # Output topics per category.
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   653
            for cat in TOPIC_CATEGORY_ORDER:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   654
                topics = topiccats.get(cat, [])
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   655
                if topics:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   656
                    if len(topiccats) > 1:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   657
                        catname = gettext(TOPIC_CATEGORY_NAMES[cat])
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   658
                        rst.append("\n%s:\n" % catname)
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   659
                    rst.append("\n")
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   660
                    for t, desc in topics:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   661
                        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
   662
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   663
        if ui.quiet:
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   664
            pass
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   665
        elif ui.verbose:
22116
161085f87b95 help: roll option list header into option formatter
Matt Mackall <mpm@selenic.com>
parents: 22115
diff changeset
   666
            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
   667
                                         commands.globalopts, ui.verbose))
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   668
            if name == 'shortlist':
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   669
                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
   670
                             "of commands)\n"))
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   671
        else:
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   672
            if name == 'shortlist':
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   673
                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
   674
                             "or 'hg -v' for details)\n"))
22115
8465625f7364 help: refactor helplist optlist mess
Matt Mackall <mpm@selenic.com>
parents: 22114
diff changeset
   675
            elif name and not full:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   676
                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
   677
                             "text)\n") % name)
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 40263
diff changeset
   678
            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
   679
                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
   680
                             "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
   681
            else:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   682
                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
   683
                             "and global options)\n")
22118
9a299c39de01 help: normalize helplist hints
Matt Mackall <mpm@selenic.com>
parents: 22117
diff changeset
   684
                           % (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
   685
        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
   686
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   687
    def helptopic(name, subtopic=None):
27379
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   688
        # Look for sub-topic entry first.
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   689
        header, doc = None, None
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   690
        if subtopic and name in subtopics:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   691
            for names, header, doc in subtopics[name]:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   692
                if subtopic in names:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   693
                    break
42393
a84564b1a0b1 help: check if a subtopic exists and raise an error if it doesn't (issue6145)
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42057
diff changeset
   694
            if not any(subtopic in s[0] for s in subtopics[name]):
a84564b1a0b1 help: check if a subtopic exists and raise an error if it doesn't (issue6145)
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42057
diff changeset
   695
                raise error.UnknownCommand(name)
27379
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   696
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   697
        if not header:
40292
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   698
            for topic in helptable:
9c6473d2038b help: splitting the topics by category
Rodrigo Damazio <rdamazio@google.com>
parents: 40291
diff changeset
   699
                names, header, doc = topic[0:3]
27379
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   700
                if name in names:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   701
                    break
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   702
            else:
2278870bb997 help: support loading sub-topics
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27378
diff changeset
   703
                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
   704
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 18746
diff changeset
   705
        rst = [minirst.section(header)]
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 18746
diff changeset
   706
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
   707
        # 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
   708
        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
   709
            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
   710
        if callable(doc):
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26371
diff changeset
   711
            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
   712
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   713
        if not ui.verbose:
22114
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   714
            omitted = _('(some details hidden, use --verbose'
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   715
                         ' 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
   716
            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
   717
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
        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
   719
            cmdutil.findcmd(name, commands.table)
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   720
            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
   721
                       "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
   722
        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
   723
            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
   724
        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
   725
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   726
    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
   727
        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
   728
            mod = extensions.find(name)
32615
c9318beb7c1a py3: convert __doc__ back to bytes in help.py
Yuya Nishihara <yuya@tcha.org>
parents: 32566
diff changeset
   729
            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
   730
        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
   731
            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
   732
            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
   733
            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
   734
                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
   735
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   736
        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
   737
            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
   738
        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
   739
            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
   740
        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
   741
        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
   742
            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
   743
            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
   744
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   745
        if not ui.verbose:
22114
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   746
            omitted = _('(some details hidden, use --verbose'
3ba1d7ca3dfd help: normalize topic and extension verbose hints
Matt Mackall <mpm@selenic.com>
parents: 22113
diff changeset
   747
                         ' 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
   748
            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
   749
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   750
        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
   751
            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
   752
                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
   753
            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
   754
                ct = {}
42057
566daffc607d cleanup: use set literals where possible
Martin von Zweigbergk <martinvonz@google.com>
parents: 42041
diff changeset
   755
            modcmds = {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
   756
            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
   757
        else:
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   758
            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
   759
                       " 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
   760
        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
   761
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   762
    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
   763
        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
   764
                                               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
   765
        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
   766
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   767
        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
   768
                              "extension:") % cmd, {ext: doc}, indent=4,
ac27b1b3be85 help: make help deprecated mention the extension
timeless <timeless@mozdev.org>
parents: 27151
diff changeset
   769
                       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
   770
        rst.append('\n')
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   771
        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
   772
                   "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
   773
        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
   774
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   775
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   776
    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
   777
    kw = opts.get('keyword')
27325
eadbbd14bdc1 help: fix help -c/help -e/help -k
timeless <timeless@mozdev.org>
parents: 27324
diff changeset
   778
    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
   779
        matches = topicmatch(ui, commands, name or '')
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   780
        helpareas = []
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   781
        if opts.get('extension'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   782
            helpareas += [('extensions', _('Extensions'))]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   783
        if opts.get('command'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   784
            helpareas += [('commands', _('Commands'))]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   785
        if not helpareas:
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   786
            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
   787
                         ('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
   788
                         ('extensions', _('Extensions')),
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   789
                         ('extensioncommands', _('Extension Commands'))]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   790
        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
   791
            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
   792
                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
   793
                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
   794
                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
   795
        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
   796
            msg = _('no matches')
29974
7109d5ddeb0c help: use single quotes in use warning
timeless <timeless@mozdev.org>
parents: 29859
diff changeset
   797
            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
   798
            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
   799
    elif name and name != 'shortlist':
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   800
        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
   801
        if unknowncmd:
26238
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   802
            queries += [helpextcmd]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   803
        if opts.get('extension'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   804
            queries += [helpext]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   805
        if opts.get('command'):
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   806
            queries += [helpcmd]
69da16b366ad help: fix help argument parsing and documentation
timeless@mozdev.org
parents: 26196
diff changeset
   807
        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
   808
            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
   809
        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
   810
            try:
27378
c709b515218e help: pass sub-topic into help query functions
Gregory Szorc <gregory.szorc@gmail.com>
parents: 27377
diff changeset
   811
                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
   812
                break
21289
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   813
            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
   814
                pass
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   815
        else:
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   816
            if unknowncmd:
c3784e3c3e8d help: suggest keyword search when no topic is found
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 21288
diff changeset
   817
                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
   818
            else:
42394
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   819
                if fullname:
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   820
                    formatname = fullname
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   821
                else:
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   822
                    formatname = name
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   823
                if subtopic:
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   824
                    hintname = subtopic
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   825
                else:
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   826
                    hintname = name
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   827
                msg = _('no such help topic: %s') % formatname
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   828
                hint = _("try 'hg help --keyword %s'") % hintname
26587
56b2bcea2529 error: get Abort from 'error' instead of 'util'
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 26436
diff changeset
   829
                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
   830
    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
   831
        # 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
   832
        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
   833
            rst = [_("Mercurial Distributed SCM\n"), '\n']
32547
0cec8ad579d4 help: convert dict to strkwargs
Augie Fackler <raf@durin42.com>
parents: 32291
diff changeset
   834
        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
   835
c0087d48ec3a help: move the majority of the help command to the help module
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17837
diff changeset
   836
    return ''.join(rst)
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   837
39339
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   838
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
   839
                  full=True, **opts):
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   840
    """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
   841
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   842
    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
   843
    """
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   844
    if keep is None:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   845
        keep = []
31265
79715ba22f9c help: avoid mutating passed-in `keep` list in `formattedhelp`
Augie Fackler <augie@google.com>
parents: 31129
diff changeset
   846
    else:
79715ba22f9c help: avoid mutating passed-in `keep` list in `formattedhelp`
Augie Fackler <augie@google.com>
parents: 31129
diff changeset
   847
        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
   848
d30867a745a1 help: rewrite parsing of help topic to not drop section name with dots
Yuya Nishihara <yuya@tcha.org>
parents: 39309
diff changeset
   849
    # <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
   850
    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
   851
    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
   852
        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
   853
        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
   854
        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
   855
            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
   856
        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
   857
            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
   858
33499
0407a51b9d8c codemod: register core configitems using a script
Jun Wu <quark@fb.com>
parents: 32619
diff changeset
   859
    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
   860
    termwidth = ui.termwidth() - 2
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   861
    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
   862
        textwidth = termwidth
42394
ad55a0a5894f help: include subtopic in error message if passed
Nathan Goldbaum <nathan12343@gmail.com>
parents: 42393
diff changeset
   863
    text = help_(ui, commands, name, fullname=fullname,
31059
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   864
                 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
   865
39308
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   866
    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
   867
    if 'verbose' in pruned:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   868
        keep.append('omitted')
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   869
    else:
2a0c8e3636b0 help: move rst formatting of help documents into help.py
Augie Fackler <augie@google.com>
parents: 30812
diff changeset
   870
        keep.append('notomitted')
39308
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   871
    blocks, pruned = minirst.parse(text, keep=keep)
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   872
    if section:
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   873
        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
   874
0a766cb1092a help: reorder section filtering flow to not format help text twice
Yuya Nishihara <yuya@tcha.org>
parents: 39308
diff changeset
   875
    # 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
   876
    # 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
   877
    # 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
   878
    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
   879
        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
   880
39308
9b800601701c help: inline minirst.format()
Yuya Nishihara <yuya@tcha.org>
parents: 37998
diff changeset
   881
    return minirst.formatplain(blocks, textwidth)