doc/gendoc.py
author Pulkit Goyal <7895pulkit@gmail.com>
Wed, 13 Jan 2021 15:42:15 +0530
changeset 46232 eb01d6d00a50
parent 45830 c102b704edb5
child 46516 921e1253c8ba
permissions -rwxr-xr-x
largefiles: remove unused imports This fixes test-check-pyflakes.t Differential Revision: https://phab.mercurial-scm.org/D9747
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
45830
c102b704edb5 global: use python3 in shebangs
Gregory Szorc <gregory.szorc@gmail.com>
parents: 44975
diff changeset
     1
#!/usr/bin/env python3
19425
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     2
"""usage: %s DOC ...
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     3
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     4
where DOC is the name of a document
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     5
"""
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
     6
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
     7
from __future__ import absolute_import
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
     8
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
     9
import os
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    10
import sys
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    11
import textwrap
27330
6fbf1159a85a doc: make gendoc.py module import policy aware
Gregory Szorc <gregory.szorc@gmail.com>
parents: 26413
diff changeset
    12
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    13
try:
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    14
    import msvcrt
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
    15
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    16
    msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    17
    msvcrt.setmode(sys.stderr.fileno(), os.O_BINARY)
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    18
except ImportError:
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    19
    pass
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    20
27330
6fbf1159a85a doc: make gendoc.py module import policy aware
Gregory Szorc <gregory.szorc@gmail.com>
parents: 26413
diff changeset
    21
# This script is executed during installs and may not have C extensions
6fbf1159a85a doc: make gendoc.py module import policy aware
Gregory Szorc <gregory.szorc@gmail.com>
parents: 26413
diff changeset
    22
# available. Relax C module requirements.
43506
9f70512ae2cf cleanup: remove pointless r-prefixes on single-quoted strings
Augie Fackler <augie@google.com>
parents: 43503
diff changeset
    23
os.environ['HGMODULEPOLICY'] = 'allow'
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    24
# import from the live mercurial repo
43503
313e3a279828 cleanup: remove pointless r-prefixes on double-quoted strings
Augie Fackler <augie@google.com>
parents: 43076
diff changeset
    25
sys.path.insert(0, "..")
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
    26
from mercurial import demandimport
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
    27
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
    28
demandimport.enable()
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
    29
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    30
from mercurial import (
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    31
    commands,
41030
c0865f3da285 py3: byteify sys.argv in gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 41004
diff changeset
    32
    encoding,
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    33
    extensions,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    34
    help,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    35
    minirst,
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    36
    pycompat,
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    37
    ui as uimod,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    38
)
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    39
from mercurial.i18n import (
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    40
    gettext,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    41
    _,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    42
)
44975
1a4b9b602e54 py3: fix broken man page generation, it was generating `(default: NUL*)`
Kyle Lippincott <spectral@google.com>
parents: 43673
diff changeset
    43
from mercurial.utils import stringutil
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    44
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    45
table = commands.table
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    46
globalopts = commands.globalopts
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    47
helptable = help.helptable
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
    48
loaddoc = help.loaddoc
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    49
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
    50
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    51
def get_desc(docstr):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    52
    if not docstr:
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    53
        return b"", b""
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    54
    # sanitize
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    55
    docstr = docstr.strip(b"\n")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    56
    docstr = docstr.rstrip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    57
    shortdesc = docstr.splitlines()[0].strip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    58
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    59
    i = docstr.find(b"\n")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    60
    if i != -1:
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
    61
        desc = docstr[i + 2 :]
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    62
    else:
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
    63
        desc = shortdesc
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
    64
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    65
    desc = textwrap.dedent(desc.decode('latin1')).encode('latin1')
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
    66
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    67
    return (shortdesc, desc)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    68
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
    69
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    70
def get_opts(opts):
11321
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    71
    for opt in opts:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    72
        if len(opt) == 5:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    73
            shortopt, longopt, default, desc, optlabel = opt
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    74
        else:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
    75
            shortopt, longopt, default, desc = opt
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    76
            optlabel = _(b"VALUE")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    77
        allopts = []
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    78
        if shortopt:
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    79
            allopts.append(b"-%s" % shortopt)
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    80
        if longopt:
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    81
            allopts.append(b"--%s" % longopt)
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
    82
        if isinstance(default, list):
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    83
            allopts[-1] += b" <%s[+]>" % optlabel
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
    84
        elif (default is not None) and not isinstance(default, bool):
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    85
            allopts[-1] += b" <%s>" % optlabel
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    86
        if b'\n' in desc:
20655
37f3be9d1541 doc: gendoc.py creates valid output for option descriptions with newlines
Simon Heimberg <simohe@besonet.ch>
parents: 20081
diff changeset
    87
            # only remove line breaks and indentation
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    88
            desc = b' '.join(l.lstrip() for l in desc.split(b'\n'))
44975
1a4b9b602e54 py3: fix broken man page generation, it was generating `(default: NUL*)`
Kyle Lippincott <spectral@google.com>
parents: 43673
diff changeset
    89
        if default:
1a4b9b602e54 py3: fix broken man page generation, it was generating `(default: NUL*)`
Kyle Lippincott <spectral@google.com>
parents: 43673
diff changeset
    90
            default = stringutil.forcebytestr(default)
1a4b9b602e54 py3: fix broken man page generation, it was generating `(default: NUL*)`
Kyle Lippincott <spectral@google.com>
parents: 43673
diff changeset
    91
            desc += _(b" (default: %s)") % default
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    92
        yield (b", ".join(allopts), desc)
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    93
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
    94
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
    95
def get_cmd(cmd, cmdtable):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    96
    d = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
    97
    attr = cmdtable[cmd]
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
    98
    cmds = cmd.lstrip(b"^").split(b"|")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
    99
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   100
    d[b'cmd'] = cmds[0]
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   101
    d[b'aliases'] = cmd.split(b"|")[1:]
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   102
    d[b'desc'] = get_desc(gettext(pycompat.getdoc(attr[0])))
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   103
    d[b'opts'] = list(get_opts(attr[1]))
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
   104
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   105
    s = b'hg ' + cmds[0]
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
   106
    if len(attr) > 2:
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   107
        if not attr[2].startswith(b'hg'):
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   108
            s += b' ' + attr[2]
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
   109
        else:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
   110
            s = attr[2]
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   111
    d[b'synopsis'] = s.strip()
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
   112
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   113
    return d
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   114
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   115
19423
5046fede7684 gendoc: rename to showdoc from show_doc
Takumi IINO <trot.thunder@gmail.com>
parents: 19322
diff changeset
   116
def showdoc(ui):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   117
    # print options
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   118
    ui.write(minirst.section(_(b"Options")))
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   119
    multioccur = False
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   120
    for optstr, desc in get_opts(globalopts):
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   121
        ui.write(b"%s\n    %s\n\n" % (optstr, desc))
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   122
        if optstr.endswith(b"[+]>"):
20081
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   123
            multioccur = True
93f9d11603d8 doc: show details of command options in pages generated by docutils
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19425
diff changeset
   124
    if multioccur:
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   125
        ui.write(_(b"\n[+] marked option can be specified multiple times\n"))
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   126
        ui.write(b"\n")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   127
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   128
    # print cmds
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   129
    ui.write(minirst.section(_(b"Commands")))
42252
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   130
    commandprinter(ui, table, minirst.subsection, minirst.subsubsection)
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
   131
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   132
    # print help topics
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   133
    # The config help topic is included in the hgrc.5 man page.
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   134
    helpprinter(ui, helptable, minirst.section, exclude=[b'config'])
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
   135
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   136
    ui.write(minirst.section(_(b"Extensions")))
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   137
    ui.write(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   138
        _(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   139
            b"This section contains help for extensions that are "
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   140
            b"distributed together with Mercurial. Help for other "
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   141
            b"extensions is available in the help system."
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   142
        )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   143
    )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   144
    ui.write(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   145
        (
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   146
            b"\n\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   147
            b".. contents::\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   148
            b"   :class: htmlonly\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   149
            b"   :local:\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   150
            b"   :depth: 1\n\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   151
        )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   152
    )
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   153
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   154
    for extensionname in sorted(allextensionnames()):
27660
512f883c234c mercurial: pass ui to extensions.load (issue5007)
Jun Wu <quark@fb.com>
parents: 27496
diff changeset
   155
        mod = extensions.load(ui, extensionname, None)
18748
6e676fb6ea44 help: use a full header for topic titles
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents: 17267
diff changeset
   156
        ui.write(minirst.subsection(extensionname))
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   157
        ui.write(b"%s\n\n" % gettext(pycompat.getdoc(mod)))
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   158
        cmdtable = getattr(mod, 'cmdtable', None)
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   159
        if cmdtable:
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   160
            ui.write(minirst.subsubsection(_(b'Commands')))
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   161
            commandprinter(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   162
                ui,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   163
                cmdtable,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   164
                minirst.subsubsubsection,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   165
                minirst.subsubsubsubsection,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   166
            )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   167
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   168
19424
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   169
def showtopic(ui, topic):
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   170
    extrahelptable = [
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   171
        ([b"common"], b'', loaddoc(b'common'), help.TOPIC_CATEGORY_MISC),
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   172
        ([b"hg.1"], b'', loaddoc(b'hg.1'), help.TOPIC_CATEGORY_CONFIG),
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   173
        ([b"hg-ssh.8"], b'', loaddoc(b'hg-ssh.8'), help.TOPIC_CATEGORY_CONFIG),
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   174
        (
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   175
            [b"hgignore.5"],
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   176
            b'',
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   177
            loaddoc(b'hgignore.5'),
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   178
            help.TOPIC_CATEGORY_CONFIG,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   179
        ),
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   180
        ([b"hgrc.5"], b'', loaddoc(b'hgrc.5'), help.TOPIC_CATEGORY_CONFIG),
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   181
        (
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   182
            [b"hgignore.5.gendoc"],
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   183
            b'',
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   184
            loaddoc(b'hgignore'),
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   185
            help.TOPIC_CATEGORY_CONFIG,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   186
        ),
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   187
        (
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   188
            [b"hgrc.5.gendoc"],
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   189
            b'',
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   190
            loaddoc(b'config'),
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   191
            help.TOPIC_CATEGORY_CONFIG,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   192
        ),
19424
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   193
    ]
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   194
    helpprinter(ui, helptable + extrahelptable, None, include=[topic])
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
   195
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   196
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   197
def helpprinter(ui, helptable, sectionfunc, include=[], exclude=[]):
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 32336
diff changeset
   198
    for h in helptable:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 32336
diff changeset
   199
        names, sec, doc = h[0:3]
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   200
        if exclude and names[0] in exclude:
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   201
            continue
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   202
        if include and names[0] not in include:
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   203
            continue
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   204
        for name in names:
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   205
            ui.write(b".. _%s:\n" % name)
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   206
        ui.write(b"\n")
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   207
        if sectionfunc:
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   208
            ui.write(sectionfunc(sec))
21793
e0b29a0c36c4 gendoc: restore use of callable() since it was readded in Python 3.2
Augie Fackler <raf@durin42.com>
parents: 20689
diff changeset
   209
        if callable(doc):
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26412
diff changeset
   210
            doc = doc(ui)
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   211
        ui.write(doc)
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   212
        ui.write(b"\n")
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
   213
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   214
42252
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   215
def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc):
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   216
    """Render restructuredtext describing a list of commands and their
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   217
    documentations, grouped by command category.
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   218
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   219
    Args:
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   220
      ui: UI object to write the output to
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   221
      cmdtable: a dict that maps a string of the command name plus its aliases
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   222
        (separated with pipes) to a 3-tuple of (the command's function, a list
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   223
        of its option descriptions, and a string summarizing available
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   224
        options). Example, with aliases added for demonstration purposes:
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   225
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   226
          'phase|alias1|alias2': (
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   227
             <function phase at 0x7f0816b05e60>,
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   228
             [ ('p', 'public', False, 'set changeset phase to public'),
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   229
               ...,
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   230
               ('r', 'rev', [], 'target revision', 'REV')],
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   231
             '[-p|-d|-s] [-f] [-r] [REV...]'
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   232
          )
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   233
      sectionfunc: minirst function to format command category headers
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   234
      subsectionfunc: minirst function to format command headers
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   235
    """
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   236
    h = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
   237
    for c, attr in cmdtable.items():
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   238
        f = c.split(b"|")[0]
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   239
        f = f.lstrip(b"^")
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
   240
        h[f] = c
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   241
    cmds = h.keys()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   242
42249
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   243
    def helpcategory(cmd):
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   244
        """Given a canonical command name from `cmds` (above), retrieve its
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   245
        help category. If helpcategory is None, default to CATEGORY_NONE.
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   246
        """
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   247
        fullname = h[cmd]
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   248
        details = cmdtable[fullname]
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   249
        helpcategory = details[0].helpcategory
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   250
        return helpcategory or help.registrar.command.CATEGORY_NONE
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   251
42250
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42249
diff changeset
   252
    cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42249
diff changeset
   253
    for cmd in cmds:
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42249
diff changeset
   254
        # If a command category wasn't registered, the command won't get
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42249
diff changeset
   255
        # rendered below, so we raise an AssertionError.
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42249
diff changeset
   256
        if helpcategory(cmd) not in cmdsbycategory:
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42249
diff changeset
   257
            raise AssertionError(
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42249
diff changeset
   258
                "The following command did not register its (category) in "
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   259
                "help.CATEGORY_ORDER: %s (%s)" % (cmd, helpcategory(cmd))
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   260
            )
42250
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42249
diff changeset
   261
        cmdsbycategory[helpcategory(cmd)].append(cmd)
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42249
diff changeset
   262
42249
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   263
    # Print the help for each command. We present the commands grouped by
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   264
    # category, and we use help.CATEGORY_ORDER as a guide for a helpful order
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   265
    # in which to present the categories.
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   266
    for category in help.CATEGORY_ORDER:
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   267
        categorycmds = cmdsbycategory[category]
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   268
        if not categorycmds:
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   269
            # Skip empty categories
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   270
            continue
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   271
        # Print a section header for the category.
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   272
        # For now, the category header is at the same level as the headers for
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   273
        # the commands in the category; this is fixed in the next commit.
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   274
        ui.write(sectionfunc(help.CATEGORY_NAMES[category]))
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   275
        # Print each command in the category
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42248
diff changeset
   276
        for f in sorted(categorycmds):
42248
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   277
            if f.startswith(b"debug"):
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   278
                continue
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   279
            d = get_cmd(h[f], cmdtable)
42252
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42250
diff changeset
   280
            ui.write(subsectionfunc(d[b'cmd']))
42248
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   281
            # short description
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   282
            ui.write(d[b'desc'][0])
12813
13fdef670c43 gendoc: support multi-line synopses
Martin Geisler <mg@lazybytes.net>
parents: 12812
diff changeset
   283
            # synopsis
42248
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   284
            ui.write(b"::\n\n")
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   285
            synopsislines = d[b'synopsis'].splitlines()
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   286
            for line in synopsislines:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   287
                # some commands (such as rebase) have a multi-line
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   288
                # synopsis
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   289
                ui.write(b"   %s\n" % line)
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   290
            ui.write(b'\n')
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   291
            # description
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   292
            ui.write(b"%s\n\n" % d[b'desc'][1])
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   293
            # options
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   294
            opt_output = list(d[b'opts'])
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   295
            if opt_output:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   296
                opts_len = max([len(line[0]) for line in opt_output])
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   297
                ui.write(_(b"Options:\n\n"))
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   298
                multioccur = False
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   299
                for optstr, desc in opt_output:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   300
                    if desc:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   301
                        s = b"%-*s  %s" % (opts_len, optstr, desc)
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   302
                    else:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   303
                        s = optstr
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   304
                    ui.write(b"%s\n" % s)
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   305
                    if optstr.endswith(b"[+]>"):
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   306
                        multioccur = True
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   307
                if multioccur:
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   308
                    ui.write(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   309
                        _(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   310
                            b"\n[+] marked option can be specified"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   311
                            b" multiple times\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   312
                        )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   313
                    )
42248
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   314
                ui.write(b"\n")
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   315
            # aliases
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   316
            if d[b'aliases']:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41037
diff changeset
   317
                ui.write(_(b"    aliases: %s\n\n") % b" ".join(d[b'aliases']))
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   318
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   319
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   320
def allextensionnames():
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   321
    return set(extensions.enabled().keys()) | set(extensions.disabled().keys())
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
   322
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42252
diff changeset
   323
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
   324
if __name__ == "__main__":
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   325
    doc = b'hg.1.gendoc'
19425
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
   326
    if len(sys.argv) > 1:
41030
c0865f3da285 py3: byteify sys.argv in gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 41004
diff changeset
   327
        doc = encoding.strtolocal(sys.argv[1])
19425
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
   328
30559
d83ca854fa21 ui: factor out ui.load() to create a ui without loading configs (API)
Yuya Nishihara <yuya@tcha.org>
parents: 29397
diff changeset
   329
    ui = uimod.ui.load()
41004
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
   330
    if doc == b'hg.1.gendoc':
26412
7e8e3c0920a6 gendoc: use real ui in place of stdout
Yuya Nishihara <yuya@tcha.org>
parents: 21793
diff changeset
   331
        showdoc(ui)
19425
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
   332
    else:
41037
2eeef8e577ac py3: byteify one more sys.argv in gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 41030
diff changeset
   333
        showtopic(ui, encoding.strtolocal(sys.argv[1]))