Mercurial > public > mercurial-scm > hg-stable

annotate doc/gendoc.py @ 46569:eb36f7a71291

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gendoc: add support for loading extensions from config settings We manage our installation and ship some extensions, enabled by default for our users, that are in hgext3rd or other directories not scanned by this tool by default. We want to generate docs during the build process, and having those docs include the extensions that users don't have to manually enable is desirable. This is *not* desirable for the normal build process, however, and should never be enabled by default. Differential Revision: https://phab.mercurial-scm.org/D9989
author Kyle Lippincott <spectral@google.com>
date Fri, 12 Feb 2021 11:06:56 -0800
parents 921e1253c8ba
children 85ec89c47a04
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
45849
c102b704edb5 global: use python3 in shebangs
Gregory Szorc <gregory.szorc@gmail.com>
parents: 44819
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
41014
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: 42281
diff changeset
15
41014
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.
43554
9f70512ae2cf cleanup: remove pointless r-prefixes on single-quoted strings
Augie Fackler <augie@google.com>
parents: 43551
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
43551
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: 42281
diff changeset
26 from mercurial import demandimport
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
27
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
28 demandimport.enable()
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
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,
41033
c0865f3da285 py3: byteify sys.argv in gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 41014
diff changeset
32 encoding,
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
33 extensions,
46568
921e1253c8ba gendoc: support defaults on customopts a bit better
Kyle Lippincott <spectral@google.com>
parents: 45849
diff changeset
34 fancyopts,
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
35 help,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
36 minirst,
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
37 pycompat,
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
38 ui as uimod,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
39 )
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
40 from mercurial.i18n import (
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
41 gettext,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
42 _,
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
43 )
44819
1a4b9b602e54 py3: fix broken man page generation, it was generating `(default: NUL*)`
Kyle Lippincott <spectral@google.com>
parents: 43714
diff changeset
44 from mercurial.utils import stringutil
28966
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
45
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
46 table = commands.table
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
47 globalopts = commands.globalopts
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
48 helptable = help.helptable
ea1fab5293ca py3: make gendoc use absolute_import
Pulkit Goyal <7895pulkit@gmail.com>
parents: 27660
diff changeset
49 loaddoc = help.loaddoc
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
50
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
51
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
52 def get_desc(docstr):
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
53 if not docstr:
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
54 return b"", b""
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
55 # sanitize
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
56 docstr = docstr.strip(b"\n")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
57 docstr = docstr.rstrip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
58 shortdesc = docstr.splitlines()[0].strip()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
59
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
60 i = docstr.find(b"\n")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
61 if i != -1:
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
62 desc = docstr[i + 2 :]
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
63 else:
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
64 desc = shortdesc
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
65
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
66 desc = textwrap.dedent(desc.decode('latin1')).encode('latin1')
12780
bdc1cf692447 gendoc: dedent documentation from docstrings
Erik Zielke <ez@aragost.com>
parents: 12777
diff changeset
67
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
68 return (shortdesc, desc)
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
69
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
70
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
71 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
72 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
73 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
74 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
75 else:
40c06bbf58be help: show value requirement and multiple occurrence of options
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 10282
diff changeset
76 shortopt, longopt, default, desc = opt
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
77 optlabel = _(b"VALUE")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
78 allopts = []
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
79 if shortopt:
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
80 allopts.append(b"-%s" % shortopt)
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
81 if longopt:
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
82 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
83 if isinstance(default, list):
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
84 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
85 elif (default is not None) and not isinstance(default, bool):
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
86 allopts[-1] += b" <%s>" % optlabel
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
87 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
88 # only remove line breaks and indentation
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
89 desc = b' '.join(l.lstrip() for l in desc.split(b'\n'))
46568
921e1253c8ba gendoc: support defaults on customopts a bit better
Kyle Lippincott <spectral@google.com>
parents: 45849
diff changeset
90 if isinstance(default, fancyopts.customopt):
921e1253c8ba gendoc: support defaults on customopts a bit better
Kyle Lippincott <spectral@google.com>
parents: 45849
diff changeset
91 default = default.getdefaultvalue()
44819
1a4b9b602e54 py3: fix broken man page generation, it was generating `(default: NUL*)`
Kyle Lippincott <spectral@google.com>
parents: 43714
diff changeset
92 if default:
1a4b9b602e54 py3: fix broken man page generation, it was generating `(default: NUL*)`
Kyle Lippincott <spectral@google.com>
parents: 43714
diff changeset
93 default = stringutil.forcebytestr(default)
1a4b9b602e54 py3: fix broken man page generation, it was generating `(default: NUL*)`
Kyle Lippincott <spectral@google.com>
parents: 43714
diff changeset
94 desc += _(b" (default: %s)") % default
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
95 yield (b", ".join(allopts), desc)
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
96
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
97
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
98 def get_cmd(cmd, cmdtable):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
99 d = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
100 attr = cmdtable[cmd]
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
101 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
102
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
103 d[b'cmd'] = cmds[0]
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
104 d[b'aliases'] = cmd.split(b"|")[1:]
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
105 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
106 d[b'opts'] = list(get_opts(attr[1]))
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
107
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
108 s = b'hg ' + cmds[0]
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
109 if len(attr) > 2:
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
110 if not attr[2].startswith(b'hg'):
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
111 s += b' ' + attr[2]
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
112 else:
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
113 s = attr[2]
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
114 d[b'synopsis'] = s.strip()
7376
fc06bd17c985 doc: handle shortened command synopses
Matt Mackall <mpm@selenic.com>
parents: 7014
diff changeset
115
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
116 return d
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
117
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
118
19423
5046fede7684 gendoc: rename to showdoc from show_doc
Takumi IINO <trot.thunder@gmail.com>
parents: 19322
diff changeset
119 def showdoc(ui):
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
120 # print options
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
121 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
122 multioccur = False
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
123 for optstr, desc in get_opts(globalopts):
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
124 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
125 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
126 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
127 if multioccur:
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
128 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
129 ui.write(b"\n")
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
130
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
131 # print cmds
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
132 ui.write(minirst.section(_(b"Commands")))
42281
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
133 commandprinter(ui, table, minirst.subsection, minirst.subsubsection)
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
134
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
135 # print help topics
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
136 # The config help topic is included in the hgrc.5 man page.
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
137 helpprinter(ui, helptable, minirst.section, exclude=[b'config'])
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
138
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
139 ui.write(minirst.section(_(b"Extensions")))
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
140 ui.write(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
141 _(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
142 b"This section contains help for extensions that are "
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
143 b"distributed together with Mercurial. Help for other "
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
144 b"extensions is available in the help system."
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
145 )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
146 )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
147 ui.write(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
148 (
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
149 b"\n\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
150 b".. contents::\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
151 b" :class: htmlonly\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
152 b" :local:\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
153 b" :depth: 1\n\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
154 )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
155 )
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
156
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
157 for extensionname in sorted(allextensionnames()):
27660
512f883c234c mercurial: pass ui to extensions.load (issue5007)
Jun Wu <quark@fb.com>
parents: 27496
diff changeset
158 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
159 ui.write(minirst.subsection(extensionname))
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
160 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
161 cmdtable = getattr(mod, 'cmdtable', None)
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
162 if cmdtable:
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
163 ui.write(minirst.subsubsection(_(b'Commands')))
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
164 commandprinter(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
165 ui,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
166 cmdtable,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
167 minirst.subsubsubsection,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
168 minirst.subsubsubsubsection,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
169 )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
170
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
171
19424
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
172 def showtopic(ui, topic):
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
173 extrahelptable = [
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
174 ([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
175 ([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
176 ([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: 42281
diff changeset
177 (
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
178 [b"hgignore.5"],
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
179 b'',
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
180 loaddoc(b'hgignore.5'),
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
181 help.TOPIC_CATEGORY_CONFIG,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
182 ),
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
183 ([b"hgrc.5"], b'', loaddoc(b'hgrc.5'), help.TOPIC_CATEGORY_CONFIG),
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
184 (
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
185 [b"hgignore.5.gendoc"],
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
186 b'',
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
187 loaddoc(b'hgignore'),
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
188 help.TOPIC_CATEGORY_CONFIG,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
189 ),
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
190 (
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
191 [b"hgrc.5.gendoc"],
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
192 b'',
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
193 loaddoc(b'config'),
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
194 help.TOPIC_CATEGORY_CONFIG,
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
195 ),
19424
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
196 ]
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
197 helpprinter(ui, helptable + extrahelptable, None, include=[topic])
762e51ce3411 gendoc: add showtopic
Takumi IINO <trot.thunder@gmail.com>
parents: 19423
diff changeset
198
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
199
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
200 def helpprinter(ui, helptable, sectionfunc, include=[], exclude=[]):
40291
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 32375
diff changeset
201 for h in helptable:
170926caf44c help: adding support for command categories
rdamazio@google.com
parents: 32375
diff changeset
202 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
203 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
204 continue
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
205 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
206 continue
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
207 for name in names:
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
208 ui.write(b".. _%s:\n" % name)
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
209 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
210 if sectionfunc:
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
211 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
212 if callable(doc):
26413
e0c572d4d112 help: pass around ui to doc loader (API)
Yuya Nishihara <yuya@tcha.org>
parents: 26412
diff changeset
213 doc = doc(ui)
19233
81d9a7f6f2e7 gendoc: extract print help topics into a dedicated function
Takumi IINO <trot.thunder@gmail.com>
parents: 19231
diff changeset
214 ui.write(doc)
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
215 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
216
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
217
42281
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
218 def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc):
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
219 """Render restructuredtext describing a list of commands and their
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
220 documentations, grouped by command category.
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
221
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
222 Args:
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
223 ui: UI object to write the output to
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
224 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: 42279
diff changeset
225 (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: 42279
diff changeset
226 of its option descriptions, and a string summarizing available
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
227 options). Example, with aliases added for demonstration purposes:
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
228
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
229 'phase|alias1|alias2': (
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
230 <function phase at 0x7f0816b05e60>,
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
231 [ ('p', 'public', False, 'set changeset phase to public'),
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
232 ...,
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
233 ('r', 'rev', [], 'target revision', 'REV')],
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
234 '[-p|-d|-s] [-f] [-r] [REV...]'
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
235 )
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
236 sectionfunc: minirst function to format command category headers
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
237 subsectionfunc: minirst function to format command headers
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
238 """
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
239 h = {}
12756
13f0acfa974a gendoc: refactor get_cmd
Erik Zielke <ez@aragost.com>
parents: 11570
diff changeset
240 for c, attr in cmdtable.items():
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
241 f = c.split(b"|")[0]
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
242 f = f.lstrip(b"^")
6488
119dff2cd592 gendoc: fix indentation
Christian Ebert <blacktrash@gmx.net>
parents: 5209
diff changeset
243 h[f] = c
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
244 cmds = h.keys()
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
245
42278
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
246 def helpcategory(cmd):
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
247 """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: 42277
diff changeset
248 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: 42277
diff changeset
249 """
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
250 fullname = h[cmd]
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
251 details = cmdtable[fullname]
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
252 helpcategory = details[0].helpcategory
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
253 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: 42277
diff changeset
254
42279
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42278
diff changeset
255 cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42278
diff changeset
256 for cmd in cmds:
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42278
diff changeset
257 # 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: 42278
diff changeset
258 # rendered below, so we raise an AssertionError.
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42278
diff changeset
259 if helpcategory(cmd) not in cmdsbycategory:
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42278
diff changeset
260 raise AssertionError(
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42278
diff changeset
261 "The following command did not register its (category) in "
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
262 "help.CATEGORY_ORDER: %s (%s)" % (cmd, helpcategory(cmd))
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
263 )
42279
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42278
diff changeset
264 cmdsbycategory[helpcategory(cmd)].append(cmd)
037a97d62625 gendoc: guarantee that all commands were processed
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42278
diff changeset
265
42278
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
266 # 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: 42277
diff changeset
267 # 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: 42277
diff changeset
268 # in which to present the categories.
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
269 for category in help.CATEGORY_ORDER:
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
270 categorycmds = cmdsbycategory[category]
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
271 if not categorycmds:
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
272 # Skip empty categories
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
273 continue
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
274 # 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: 42277
diff changeset
275 # 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: 42277
diff changeset
276 # 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: 42277
diff changeset
277 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: 42277
diff changeset
278 # Print each command in the category
3816e361e3d8 gendoc: group commands by category in man page and HTML help
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42277
diff changeset
279 for f in sorted(categorycmds):
42277
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
280 if f.startswith(b"debug"):
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
281 continue
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
282 d = get_cmd(h[f], cmdtable)
42281
a42cc325b682 gendoc: nest command headers under category headers
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 42279
diff changeset
283 ui.write(subsectionfunc(d[b'cmd']))
42277
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
284 # short description
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
285 ui.write(d[b'desc'][0])
12813
13fdef670c43 gendoc: support multi-line synopses
Martin Geisler <mg@lazybytes.net>
parents: 12812
diff changeset
286 # synopsis
42277
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
287 ui.write(b"::\n\n")
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
288 synopsislines = d[b'synopsis'].splitlines()
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
289 for line in synopsislines:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
290 # 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: 41040
diff changeset
291 # synopsis
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
292 ui.write(b" %s\n" % line)
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
293 ui.write(b'\n')
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
294 # description
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
295 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: 41040
diff changeset
296 # options
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
297 opt_output = list(d[b'opts'])
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
298 if opt_output:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
299 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: 41040
diff changeset
300 ui.write(_(b"Options:\n\n"))
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
301 multioccur = False
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
302 for optstr, desc in opt_output:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
303 if desc:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
304 s = b"%-*s %s" % (opts_len, optstr, desc)
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
305 else:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
306 s = optstr
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
307 ui.write(b"%s\n" % s)
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
308 if optstr.endswith(b"[+]>"):
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
309 multioccur = True
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
310 if multioccur:
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
311 ui.write(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
312 _(
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
313 b"\n[+] marked option can be specified"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
314 b" multiple times\n"
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
315 )
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
316 )
42277
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
317 ui.write(b"\n")
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
318 # aliases
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
319 if d[b'aliases']:
0786b791b3b5 gendoc: indent loop to make next patch more legible
Sietse Brouwer <sbbrouwer@gmail.com>
parents: 41040
diff changeset
320 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
321
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
322
12781
0d09991f91ee gendoc: automatically create help for default extensions.
Erik Zielke <ez@aragost.com>
parents: 12780
diff changeset
323 def allextensionnames():
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
324 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
325
43076
2372284d9457 formatting: blacken the codebase
Augie Fackler <augie@google.com>
parents: 42281
diff changeset
326
1814
7956893e8458 generate hg manpage from commands.py docstring
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
diff changeset
327 if __name__ == "__main__":
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
328 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
329 if len(sys.argv) > 1:
41033
c0865f3da285 py3: byteify sys.argv in gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 41014
diff changeset
330 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
331
30564
d83ca854fa21 ui: factor out ui.load() to create a ui without loading configs (API)
Yuya Nishihara <yuya@tcha.org>
parents: 29397
diff changeset
332 ui = uimod.ui.load()
46569
eb36f7a71291 gendoc: add support for loading extensions from config settings
Kyle Lippincott <spectral@google.com>
parents: 46568
diff changeset
333 # Trigger extensions to load. This is disabled by default because it uses
eb36f7a71291 gendoc: add support for loading extensions from config settings
Kyle Lippincott <spectral@google.com>
parents: 46568
diff changeset
334 # the current user's configuration, which is often not what is wanted.
eb36f7a71291 gendoc: add support for loading extensions from config settings
Kyle Lippincott <spectral@google.com>
parents: 46568
diff changeset
335 if encoding.environ.get(b'GENDOC_LOAD_CONFIGURED_EXTENSIONS', b'0') != b'0':
eb36f7a71291 gendoc: add support for loading extensions from config settings
Kyle Lippincott <spectral@google.com>
parents: 46568
diff changeset
336 extensions.loadall(ui)
eb36f7a71291 gendoc: add support for loading extensions from config settings
Kyle Lippincott <spectral@google.com>
parents: 46568
diff changeset
337
41014
e10641c48fa7 py3: byteify gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 40294
diff changeset
338 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
339 showdoc(ui)
19425
81fbd4e66ff5 gendoc: dispatch print document content by commandline arguments
Takumi IINO <trot.thunder@gmail.com>
parents: 19424
diff changeset
340 else:
41040
2eeef8e577ac py3: byteify one more sys.argv in gendoc.py
Matt Harbison <matt_harbison@yahoo.com>
parents: 41033
diff changeset
341 showtopic(ui, encoding.strtolocal(sys.argv[1]))