Mercurial > hg

comparison doc/gendoc.py @ 12781:0d09991f91ee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gendoc: automatically create help for default extensions. Adds a section in the hg.1 manpage and corresponding hg.1.html file. Each extension is listed with its module docstring, followed by the commands defined by that extendsion. Creates help for extensions by extracting doc strings from the extension modules and its commands.
author Erik Zielke <ez@aragost.com>
date Wed, 20 Oct 2010 17:45:09 +0200
parents bdc1cf692447
children e0e8b123b75e
comparison
equal deleted inserted replaced
12780:bdc1cf692447 12781:0d09991f91ee
6 from mercurial import demandimport; demandimport.enable() 6 from mercurial import demandimport; demandimport.enable()
7 from mercurial import encoding 7 from mercurial import encoding
8 from mercurial.commands import table, globalopts 8 from mercurial.commands import table, globalopts
9 from mercurial.i18n import _ 9 from mercurial.i18n import _
10 from mercurial.help import helptable 10 from mercurial.help import helptable
11 from mercurial import extensions
11 12
12 def get_desc(docstr): 13 def get_desc(docstr):
13 if not docstr: 14 if not docstr:
14 return "", "" 15 return "", ""
15 # sanitize 16 # sanitize
65 ui.write("%s\n%s\n\n" % (s, "-" * encoding.colwidth(s))) 66 ui.write("%s\n%s\n\n" % (s, "-" * encoding.colwidth(s)))
66 67
67 def subsection(ui, s): 68 def subsection(ui, s):
68 ui.write("%s\n%s\n\n" % (s, '"' * encoding.colwidth(s))) 69 ui.write("%s\n%s\n\n" % (s, '"' * encoding.colwidth(s)))
69 70
71 def subsubsection(ui, s):
72 ui.write("%s\n%s\n\n" % (s, "." * encoding.colwidth(s)))
73
74 def subsubsubsection(ui, s):
75 ui.write("%s\n%s\n\n" % (s, "#" * encoding.colwidth(s)))
76
70 77
71 def show_doc(ui): 78 def show_doc(ui):
72 # print options 79 # print options
73 section(ui, _("Options")) 80 section(ui, _("Options"))
74 for optstr, desc in get_opts(globalopts): 81 for optstr, desc in get_opts(globalopts):
75 ui.write("%s\n%s\n\n" % (optstr, desc)) 82 ui.write("%s\n%s\n\n" % (optstr, desc))
76 83
77 # print cmds 84 # print cmds
78 section(ui, _("Commands")) 85 section(ui, _("Commands"))
79 commandprinter(ui, table) 86 commandprinter(ui, table, subsection)
80 87
81 # print topics 88 # print topics
82 for names, sec, doc in helptable: 89 for names, sec, doc in helptable:
83 for name in names: 90 for name in names:
84 ui.write(".. _%s:\n" % name) 91 ui.write(".. _%s:\n" % name)
87 if hasattr(doc, '__call__'): 94 if hasattr(doc, '__call__'):
88 doc = doc() 95 doc = doc()
89 ui.write(doc) 96 ui.write(doc)
90 ui.write("\n") 97 ui.write("\n")
91 98
92 def commandprinter(ui, cmdtable): 99 section(ui, _("Extensions"))
100 ui.write(_("This section contains help for extensions that is distributed "
101 "together with Mercurial. Help for other extensions is available "
102 "in the help system."))
103 ui.write("\n\n"
104 ".. contents::\n"
105 " :class: htmlonly\n"
106 " :local:\n"
107 " :depth: 1\n\n")
108
109 for extensionname in sorted(allextensionnames()):
110 mod = extensions.load(None, extensionname, None)
111 subsection(ui, extensionname)
112 ui.write("%s\n\n" % mod.__doc__)
113 cmdtable = getattr(mod, 'cmdtable', None)
114 if cmdtable:
115 subsubsection(ui, _('Commands'))
116 commandprinter(ui, cmdtable, subsubsubsection)
117
118 def commandprinter(ui, cmdtable, sectionfunc):
93 h = {} 119 h = {}
94 for c, attr in cmdtable.items(): 120 for c, attr in cmdtable.items():
95 f = c.split("|")[0] 121 f = c.split("|")[0]
96 f = f.lstrip("^") 122 f = f.lstrip("^")
97 h[f] = c 123 h[f] = c
100 126
101 for f in cmds: 127 for f in cmds:
102 if f.startswith("debug"): 128 if f.startswith("debug"):
103 continue 129 continue
104 d = get_cmd(h[f], cmdtable) 130 d = get_cmd(h[f], cmdtable)
105 subsection(ui, d['cmd']) 131 sectionfunc(ui, d['cmd'])
106 # synopsis 132 # synopsis
107 ui.write("``%s``\n" % d['synopsis'].replace("hg ","", 1)) 133 ui.write("``%s``\n" % d['synopsis'].replace("hg ","", 1))
108 ui.write("\n") 134 ui.write("\n")
109 # description 135 # description
110 ui.write("%s\n\n" % d['desc'][1]) 136 ui.write("%s\n\n" % d['desc'][1])
123 # aliases 149 # aliases
124 if d['aliases']: 150 if d['aliases']:
125 ui.write(_(" aliases: %s\n\n") % " ".join(d['aliases'])) 151 ui.write(_(" aliases: %s\n\n") % " ".join(d['aliases']))
126 152
127 153
154 def allextensionnames():
155 extensionnames = []
156
157 extensionsdictionary = extensions.enabled()[0]
158 extensionnames.extend(extensionsdictionary.keys())
159
160 extensionsdictionary = extensions.disabled()[0]
161 extensionnames.extend(extensionsdictionary.keys())
162
163 return extensionnames
164
165
128 if __name__ == "__main__": 166 if __name__ == "__main__":
129 show_doc(sys.stdout) 167 show_doc(sys.stdout)