D6324: help: register the 'gpg' command category and give it a description

[Sietse (Sietse Brouwer)]

Sietse added a comment.


  **NB: I was wrong about extensions not using helpcategories. I checked 
something different than I thought I had. They do add categories to their 
commands.**
  
  Currently (i.e. after this patch stack, because it has been accepted) the 
hierarchy (in the man page / HTML help) is like so (ignoring the fact that man 
pages flatten the last few levels of the hierarchy due to less levels). As you 
can see, even when a command has an existing category the command will be 
displayed in that category **nested underneath the extension,** rather than 
merged into the existing command category. As long as that arrangement is used, 
I'd say it reduces the value of re-using existing command categories.
  
  - COMMANDS
- Repository creation
- clone
- init
  - Next category ...
- more commands ...
  - EXTENSIONS
- absorb
  - Commands
- Change creation
  - absorb
- acl
  - Commands
- more categories ...
  - more commands ...
- more extensions...
  - Commands
- more categories...
  - more commands...
  
  Perhaps something like this would be better. It would group by category; 
extensions could add commands to existing categories; commands from extensions 
would be marked as such.
  
  - COMMANDS
- Working directory management
  - status:show changed files in the working directory
  - summary:   summarize working directory state
  - update:update working directory (or switch revisions)
  - next (evolve): update to child commit, evolving history if needed
  - prev (evolve): update to parent commit
  
  Is this still the right medium for this discussion? I'm naturally interested 
because I read the code recently, but I don't want to overwhelm you with 
bikeshedding.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6324

To: Sietse, #hg-reviewers, martinvonz
Cc: rdamazio, martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6324: help: register the 'gpg' command category and give it a description

[Sietse (Sietse Brouwer)]

Sietse added a comment.


  In https://phab.mercurial-scm.org/D6324#92158, @martinvonz wrote:
  
  > [registering the `gpg` command category] doesn't actually seem to work for 
making it appear in `hg help`.
  
  
  Perhaps, instead of doing work to group extension commands by category, the 
commands should be grouped under the extension. Nearly all my (enabled and 
disabled) extensions have 5 commands or less; only evolve and mq have more (17 
+ 7 debug, and 26, respectively). (Almost) None of them use any command 
categories. Only GPG does, but that uses the same category for all its commands.
  
  The only reason that the help pages currently group extension functions by 
command category is that gendoc.py currently uses the same `commandprinter` 
function first to print the main command table, and then once per extension to 
render the extension's commands. I would be willing to separate that 
functionality so that extensions could have their own rendering function, which 
ignores categories. Shall I take that on?
  
  > ! In https://phab.mercurial-scm.org/D6324#92354, @rdamazio wrote:
  >  I need to migrate Google's extension out of the internal version of help 
(now that I've upstreamed the help changes), I'll definitely need to mess with 
categories for that, too.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6324

To: Sietse, #hg-reviewers, martinvonz
Cc: rdamazio, martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6328: minirst: support subsubsubsubsections (header level 5) with marker ''''

[Sietse (Sietse Brouwer)]

This revision was automatically updated to reflect the committed changes.
Closed by commit rHGf9cdd732cb58: minirst: support subsubsubsubsections (header 
level 5) with marker  (authored by Sietse, committed by 
).

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6328?vs=14961&id=15014

REVISION DETAIL
  https://phab.mercurial-scm.org/D6328

AFFECTED FILES
  mercurial/minirst.py

CHANGE DETAILS

diff --git a/mercurial/minirst.py b/mercurial/minirst.py
--- a/mercurial/minirst.py
+++ b/mercurial/minirst.py
@@ -44,6 +44,9 @@
 def subsubsubsection(s):
 return "%s\n%s\n\n" % (s, "." * encoding.colwidth(s))
 
+def subsubsubsubsection(s):
+return "%s\n%s\n\n" % (s, "'" * encoding.colwidth(s))
+
 def replace(text, substs):
 '''
 Apply a list of (find, replace) pairs to a text.



To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6329: gendoc: nest command headers under category headers

[Sietse (Sietse Brouwer)]

This revision was automatically updated to reflect the committed changes.
Closed by commit rHGa42cc325b682: gendoc: nest command headers under category 
headers (authored by Sietse, committed by ).

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6329?vs=15000&id=15015

REVISION DETAIL
  https://phab.mercurial-scm.org/D6329

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -120,7 +120,7 @@
 
 # print cmds
 ui.write(minirst.section(_(b"Commands")))
-commandprinter(ui, table, minirst.subsection)
+commandprinter(ui, table, minirst.subsection, minirst.subsubsection)
 
 # print help topics
 # The config help topic is included in the hgrc.5 man page.
@@ -143,7 +143,8 @@
 cmdtable = getattr(mod, 'cmdtable', None)
 if cmdtable:
 ui.write(minirst.subsubsection(_(b'Commands')))
-commandprinter(ui, cmdtable, minirst.subsubsubsection)
+commandprinter(ui, cmdtable, minirst.subsubsubsection,
+minirst.subsubsubsubsection)
 
 def showtopic(ui, topic):
 extrahelptable = [
@@ -177,7 +178,27 @@
 ui.write(doc)
 ui.write(b"\n")
 
-def commandprinter(ui, cmdtable, sectionfunc):
+def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc):
+"""Render restructuredtext describing a list of commands and their
+documentations, grouped by command category.
+
+Args:
+  ui: UI object to write the output to
+  cmdtable: a dict that maps a string of the command name plus its aliases
+(separated with pipes) to a 3-tuple of (the command's function, a list
+of its option descriptions, and a string summarizing available
+options). Example, with aliases added for demonstration purposes:
+
+  'phase|alias1|alias2': (
+ ,
+ [ ('p', 'public', False, 'set changeset phase to public'),
+   ...,
+   ('r', 'rev', [], 'target revision', 'REV')],
+ '[-p|-d|-s] [-f] [-r] [REV...]'
+  )
+  sectionfunc: minirst function to format command category headers
+  subsectionfunc: minirst function to format command headers
+"""
 h = {}
 for c, attr in cmdtable.items():
 f = c.split(b"|")[0]
@@ -221,7 +242,7 @@
 if f.startswith(b"debug"):
 continue
 d = get_cmd(h[f], cmdtable)
-ui.write(sectionfunc(d[b'cmd']))
+ui.write(subsectionfunc(d[b'cmd']))
 # short description
 ui.write(d[b'desc'][0])
 # synopsis



To: Sietse, #hg-reviewers
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6327: gendoc: guarantee that all commands were processed

[Sietse (Sietse Brouwer)]

This revision was automatically updated to reflect the committed changes.
Closed by commit rHG037a97d62625: gendoc: guarantee that all commands were 
processed (authored by Sietse, committed by ).

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6327?vs=14999&id=15013

REVISION DETAIL
  https://phab.mercurial-scm.org/D6327

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -194,13 +194,19 @@
 helpcategory = details[0].helpcategory
 return helpcategory or help.registrar.command.CATEGORY_NONE
 
+cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
+for cmd in cmds:
+# If a command category wasn't registered, the command won't get
+# rendered below, so we raise an AssertionError.
+if helpcategory(cmd) not in cmdsbycategory:
+raise AssertionError(
+"The following command did not register its (category) in "
+"help.CATEGORY_ORDER: %s (%s)" % (cmd, helpcategory(cmd)))
+cmdsbycategory[helpcategory(cmd)].append(cmd)
+
 # Print the help for each command. We present the commands grouped by
 # category, and we use help.CATEGORY_ORDER as a guide for a helpful order
 # in which to present the categories.
-cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
-for cmd in cmds:
-cmdsbycategory[helpcategory(cmd)].append(cmd)
-
 for category in help.CATEGORY_ORDER:
 categorycmds = cmdsbycategory[category]
 if not categorycmds:
@@ -250,7 +256,6 @@
 if d[b'aliases']:
 ui.write(_(b"aliases: %s\n\n") % b" ".join(d[b'aliases']))
 
-
 def allextensionnames():
 return set(extensions.enabled().keys()) | set(extensions.disabled().keys())
 



To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6325: gendoc: indent loop to make next patch more legible

[Sietse (Sietse Brouwer)]

This revision was automatically updated to reflect the committed changes.
Closed by commit rHG0786b791b3b5: gendoc: indent loop to make next patch more 
legible (authored by Sietse, committed by ).

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6325?vs=14958&id=15011

REVISION DETAIL
  https://phab.mercurial-scm.org/D6325

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -185,44 +185,45 @@
 h[f] = c
 cmds = h.keys()
 
-for f in sorted(cmds):
-if f.startswith(b"debug"):
-continue
-d = get_cmd(h[f], cmdtable)
-ui.write(sectionfunc(d[b'cmd']))
-# short description
-ui.write(d[b'desc'][0])
-# synopsis
-ui.write(b"::\n\n")
-synopsislines = d[b'synopsis'].splitlines()
-for line in synopsislines:
-# some commands (such as rebase) have a multi-line
+if True:
+for f in sorted(cmds):
+if f.startswith(b"debug"):
+continue
+d = get_cmd(h[f], cmdtable)
+ui.write(sectionfunc(d[b'cmd']))
+# short description
+ui.write(d[b'desc'][0])
 # synopsis
-ui.write(b"   %s\n" % line)
-ui.write(b'\n')
-# description
-ui.write(b"%s\n\n" % d[b'desc'][1])
-# options
-opt_output = list(d[b'opts'])
-if opt_output:
-opts_len = max([len(line[0]) for line in opt_output])
-ui.write(_(b"Options:\n\n"))
-multioccur = False
-for optstr, desc in opt_output:
-if desc:
-s = b"%-*s  %s" % (opts_len, optstr, desc)
-else:
-s = optstr
-ui.write(b"%s\n" % s)
-if optstr.endswith(b"[+]>"):
-multioccur = True
-if multioccur:
-ui.write(_(b"\n[+] marked option can be specified"
-   b" multiple times\n"))
-ui.write(b"\n")
-# aliases
-if d[b'aliases']:
-ui.write(_(b"aliases: %s\n\n") % b" ".join(d[b'aliases']))
+ui.write(b"::\n\n")
+synopsislines = d[b'synopsis'].splitlines()
+for line in synopsislines:
+# some commands (such as rebase) have a multi-line
+# synopsis
+ui.write(b"   %s\n" % line)
+ui.write(b'\n')
+# description
+ui.write(b"%s\n\n" % d[b'desc'][1])
+# options
+opt_output = list(d[b'opts'])
+if opt_output:
+opts_len = max([len(line[0]) for line in opt_output])
+ui.write(_(b"Options:\n\n"))
+multioccur = False
+for optstr, desc in opt_output:
+if desc:
+s = b"%-*s  %s" % (opts_len, optstr, desc)
+else:
+s = optstr
+ui.write(b"%s\n" % s)
+if optstr.endswith(b"[+]>"):
+multioccur = True
+if multioccur:
+ui.write(_(b"\n[+] marked option can be specified"
+   b" multiple times\n"))
+ui.write(b"\n")
+# aliases
+if d[b'aliases']:
+ui.write(_(b"aliases: %s\n\n") % b" ".join(d[b'aliases']))
 
 
 def allextensionnames():



To: Sietse, #hg-reviewers
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6326: gendoc: group commands by category in man page and HTML help

[Sietse (Sietse Brouwer)]

This revision was automatically updated to reflect the committed changes.
Closed by commit rHG3816e361e3d8: gendoc: group commands by category in man 
page and HTML help (authored by Sietse, committed by ).

CHANGED PRIOR TO COMMIT
  https://phab.mercurial-scm.org/D6326?vs=14998&id=15012#toc

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6326?vs=14998&id=15012

REVISION DETAIL
  https://phab.mercurial-scm.org/D6326

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -185,8 +185,33 @@
 h[f] = c
 cmds = h.keys()
 
-if True:
-for f in sorted(cmds):
+def helpcategory(cmd):
+"""Given a canonical command name from `cmds` (above), retrieve its
+help category. If helpcategory is None, default to CATEGORY_NONE.
+"""
+fullname = h[cmd]
+details = cmdtable[fullname]
+helpcategory = details[0].helpcategory
+return helpcategory or help.registrar.command.CATEGORY_NONE
+
+# Print the help for each command. We present the commands grouped by
+# category, and we use help.CATEGORY_ORDER as a guide for a helpful order
+# in which to present the categories.
+cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
+for cmd in cmds:
+cmdsbycategory[helpcategory(cmd)].append(cmd)
+
+for category in help.CATEGORY_ORDER:
+categorycmds = cmdsbycategory[category]
+if not categorycmds:
+# Skip empty categories
+continue
+# Print a section header for the category.
+# For now, the category header is at the same level as the headers for
+# the commands in the category; this is fixed in the next commit.
+ui.write(sectionfunc(help.CATEGORY_NAMES[category]))
+# Print each command in the category
+for f in sorted(categorycmds):
 if f.startswith(b"debug"):
 continue
 d = get_cmd(h[f], cmdtable)



To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6329: gendoc: nest command headers under category headers

[Sietse (Sietse Brouwer)]

Sietse added inline comments.

INLINE COMMENTS

> gendoc.py:201
> +  subsectionfunc: minirst function to format command headers
> +"""
>  h = {}

Could somebody confirm the new `hg.1` man page and `hg.1.html` output look 
okay? I've linked them (and the originals) in the comment at the top of this 
page above. They are extremely user-facing, so I'm anxious to have a second 
pair of eyes go over them.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6329

To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6327: gendoc: guarantee that all commands were processed

[Sietse (Sietse Brouwer)]

Sietse marked 2 inline comments as done.
Sietse added inline comments.

INLINE COMMENTS

> martinvonz wrote in gendoc.py:200
> I think a previous version of this patch ignored uncategorized debug 
> commands. Will this version error out?

It doesn't error out, I checked before uploading. Debug commands have 
CATEGORY_NONE; see also below.

The purpose of this patch is to give confidence that no commands got 'lost' as 
we moved from 'process every command' (which guarantees every commands gets 
processed) to 'process every registered category' (where commands can get 
skipped if their category isn't registered).

The previous version of this patch compared an expected list of commands to a 
log of processed commands. Because the main command-rendering loop skipped 
debug commands, I manually removed them from the expected list, too. That's why 
it ignored debug commands.

The current version of this patch checks at command-sorting time that every 
command is part of a registered category. Commands with no category (such as 
debug commands) get sorted into `CATEGORY_NONE`, which is a known category 
displayed as "Uncategorized commands". We've guaranteed that the 
command-rendering loop will see every command, and what it skips or keeps is up 
to the rendering logic.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6327

To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6326: gendoc: group commands by category in man page and HTML help

[Sietse (Sietse Brouwer)]

Sietse marked 2 inline comments as done.
Sietse added inline comments.

INLINE COMMENTS

> martinvonz wrote in gendoc.py:188
> Interesting examples.
> 
> I found the `commithook()` quite confusing. I've sent 
> https://phab.mercurial-scm.org/D6336 to remove the arguments from it.
> 
> As you said, the `def one`argument is overridden in one place, so I don't 
> think that's a good comparison.
> 
> The `def doit` actually uses the `remote=remote` as a trick for creating the 
> variable in local scope.
> 
> Even if there are a few more valid cases, the vast majority seems to be just 
> accessing the variables from the closure.

Fair enough. I've removed the outer-scope variables from the function's 
signature, so now the function closes over them instead.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6326

To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6329: gendoc: nest command headers under category headers

[Sietse (Sietse Brouwer)]

Sietse updated this revision to Diff 15000.

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6329?vs=14991&id=15000

REVISION DETAIL
  https://phab.mercurial-scm.org/D6329

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -120,7 +120,7 @@
 
 # print cmds
 ui.write(minirst.section(_(b"Commands")))
-commandprinter(ui, table, minirst.subsection)
+commandprinter(ui, table, minirst.subsection, minirst.subsubsection)
 
 # print help topics
 # The config help topic is included in the hgrc.5 man page.
@@ -143,7 +143,8 @@
 cmdtable = getattr(mod, 'cmdtable', None)
 if cmdtable:
 ui.write(minirst.subsubsection(_(b'Commands')))
-commandprinter(ui, cmdtable, minirst.subsubsubsection)
+commandprinter(ui, cmdtable, minirst.subsubsubsection,
+minirst.subsubsubsubsection)
 
 def showtopic(ui, topic):
 extrahelptable = [
@@ -177,7 +178,27 @@
 ui.write(doc)
 ui.write(b"\n")
 
-def commandprinter(ui, cmdtable, sectionfunc):
+def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc):
+"""Render restructuredtext describing a list of commands and their
+documentations, grouped by command category.
+
+Args:
+  ui: UI object to write the output to
+  cmdtable: a dict that maps a string of the command name plus its aliases
+(separated with pipes) to a 3-tuple of (the command's function, a list
+of its option descriptions, and a string summarizing available
+options). Example, with aliases added for demonstration purposes:
+
+  'phase|alias1|alias2': (
+ ,
+ [ ('p', 'public', False, 'set changeset phase to public'),
+   ...,
+   ('r', 'rev', [], 'target revision', 'REV')],
+ '[-p|-d|-s] [-f] [-r] [REV...]'
+  )
+  sectionfunc: minirst function to format command category headers
+  subsectionfunc: minirst function to format command headers
+"""
 h = {}
 for c, attr in cmdtable.items():
 f = c.split(b"|")[0]
@@ -220,7 +241,7 @@
 if f.startswith(b"debug"):
 continue
 d = get_cmd(h[f], cmdtable)
-ui.write(sectionfunc(d[b'cmd']))
+ui.write(subsectionfunc(d[b'cmd']))
 # short description
 ui.write(d[b'desc'][0])
 # synopsis



To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6327: gendoc: guarantee that all commands were processed

[Sietse (Sietse Brouwer)]

Sietse updated this revision to Diff 14999.

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6327?vs=14990&id=14999

REVISION DETAIL
  https://phab.mercurial-scm.org/D6327

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -194,13 +194,19 @@
 helpcategory = details[0].helpcategory
 return helpcategory or help.registrar.command.CATEGORY_NONE
 
+cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
+for cmd in cmds:
+# If a command category wasn't registered, the command won't get
+# rendered below, so we raise an AssertionError.
+if helpcategory(cmd) not in cmdsbycategory:
+raise AssertionError(
+"The following command did not register its (category) in "
+"help.CATEGORY_ORDER: %s (%s)" % (cmd, helpcategory(cmd)))
+cmdsbycategory[helpcategory(cmd)].append(cmd)
+
 # Print the help for each command. We present the commands grouped by
 # category, and we use help.CATEGORY_ORDER as a guide for a helpful order
 # in which to present the categories.
-cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
-for cmd in cmds:
-cmdsbycategory[helpcategory(cmd)].append(cmd)
-
 for category in help.CATEGORY_ORDER:
 categorycmds = cmdsbycategory[category]
 if not categorycmds:
@@ -249,7 +255,6 @@
 if d[b'aliases']:
 ui.write(_(b"aliases: %s\n\n") % b" ".join(d[b'aliases']))
 
-
 def allextensionnames():
 return set(extensions.enabled().keys()) | set(extensions.disabled().keys())
 



To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6326: gendoc: group commands by category in man page and HTML help

[Sietse (Sietse Brouwer)]

Sietse updated this revision to Diff 14998.

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6326?vs=14989&id=14998

REVISION DETAIL
  https://phab.mercurial-scm.org/D6326

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -185,8 +185,32 @@
 h[f] = c
 cmds = h.keys()
 
-if True:
-for f in sorted(cmds):
+def helpcategory(cmd):
+"""Given a canonical command name from `cmds` (above), retrieve its
+help category. If helpcategory is None, default to CATEGORY_NONE.
+"""
+fullname = h[cmd]
+details = cmdtable[fullname]
+helpcategory = details[0].helpcategory
+return helpcategory or help.registrar.command.CATEGORY_NONE
+
+# Print the help for each command. We present the commands grouped by
+# category, and we use help.CATEGORY_ORDER as a guide for a helpful order
+# in which to present the categories.
+cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
+for cmd in cmds:
+cmdsbycategory[helpcategory(cmd)].append(cmd)
+
+for category in help.CATEGORY_ORDER:
+categorycmds = cmdsbycategory[category]
+if not categorycmds:
+continue  # Skip empty categories
+# Print a section header for the category.
+# For now, the category header is at the same level as the headers for
+# the commands in the category; this is fixed in the next commit.
+ui.write(sectionfunc(help.CATEGORY_NAMES[category]))
+# Print each command in the category
+for f in sorted(categorycmds):
 if f.startswith(b"debug"):
 continue
 d = get_cmd(h[f], cmdtable)



To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6324: help: register the 'gpg' command category and give it a description

[Sietse (Sietse Brouwer)]

This revision was automatically updated to reflect the committed changes.
Closed by commit rHGade02721d3fa: help: register the 'gpg' command 
category and give it a description (authored by Sietse, committed by ).

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6324?vs=14957&id=14993

REVISION DETAIL
  https://phab.mercurial-scm.org/D6324

AFFECTED FILES
  hgext/gpg.py

CHANGE DETAILS

diff --git a/hgext/gpg.py b/hgext/gpg.py
--- a/hgext/gpg.py
+++ b/hgext/gpg.py
@@ -49,6 +49,11 @@
 
 # Custom help category
 _HELP_CATEGORY = 'gpg'
+help.CATEGORY_ORDER.insert(
+help.CATEGORY_ORDER.index(registrar.command.CATEGORY_HELP),
+_HELP_CATEGORY
+)
+help.CATEGORY_NAMES[_HELP_CATEGORY] = 'Signing changes (GPG)'
 
 class gpg(object):
 def __init__(self, path, key=None):



To: Sietse, #hg-reviewers, martinvonz
Cc: rdamazio, martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6326: gendoc: group commands by category in man page and HTML help

[Sietse (Sietse Brouwer)]

Sietse marked 2 inline comments as done.
Sietse added inline comments.

INLINE COMMENTS

> martinvonz wrote in gendoc.py:188
> Looks like just want `h` and `cmdtable` from the outer scope. They are 
> available without this trick, so you can just delete the two arguments here.

I've marked your comment about capturing/passing `h` and `cmdtable` "Done" in 
the sense of "replied to". I'm not sure how Phabricator's flow works -- "Done" 
seemed most likely to keep the flow going, but I do remain open to any reply by 
you (which I will then not bikeshed, because this is ultimately trivial :-P)

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6326

To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6326: gendoc: group commands by category in man page and HTML help

[Sietse (Sietse Brouwer)]

Sietse marked 3 inline comments as done.
Sietse added inline comments.

INLINE COMMENTS

> martinvonz wrote in gendoc.py:188
> Looks like just want `h` and `cmdtable` from the outer scope. They are 
> available without this trick, so you can just delete the two arguments here.

Passing `h=h, cmdtable=cmdtable` as default args is to make it obvious to the 
reader which data the function depends on. I realize it can also silently close 
over the variables in the outer scope, but I think this helps legibility.

Other places in the Mercurial codebase that define an inner function, and make 
a captured value obvious by passing it as a default argument:

- `def commithook` inside `def commit` in `localrepo.py`
- `def one` inside `def _showcompatlist` in `templateutil.py` (edge case, as 
the default arg is actually overridden once)
- `def doit` inside `def debugdiscovery` in `debugcommands.py

I'd say leave this as is, but I'll let you make the call and follow that.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6326

To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6329: gendoc: nest command headers under category headers

[Sietse (Sietse Brouwer)]

Sietse updated this revision to Diff 14991.

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6329?vs=14962&id=14991

REVISION DETAIL
  https://phab.mercurial-scm.org/D6329

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -120,7 +120,7 @@
 
 # print cmds
 ui.write(minirst.section(_(b"Commands")))
-commandprinter(ui, table, minirst.subsection)
+commandprinter(ui, table, minirst.subsection, minirst.subsubsection)
 
 # print help topics
 # The config help topic is included in the hgrc.5 man page.
@@ -143,7 +143,8 @@
 cmdtable = getattr(mod, 'cmdtable', None)
 if cmdtable:
 ui.write(minirst.subsubsection(_(b'Commands')))
-commandprinter(ui, cmdtable, minirst.subsubsubsection)
+commandprinter(ui, cmdtable, minirst.subsubsubsection,
+minirst.subsubsubsubsection)
 
 def showtopic(ui, topic):
 extrahelptable = [
@@ -177,7 +178,27 @@
 ui.write(doc)
 ui.write(b"\n")
 
-def commandprinter(ui, cmdtable, sectionfunc):
+def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc):
+"""Render restructuredtext describing a list of commands and their
+documentations, grouped by command category.
+
+Args:
+  ui: UI object to write the output to
+  cmdtable: a dict that maps a string of the command name plus its aliases
+(separated with pipes) to a 3-tuple of (the command's function, a list
+of its option descriptions, and a string summarizing available
+options). Example, with aliases added for demonstration purposes:
+
+  'phase|alias1|alias2': (
+ ,
+ [ ('p', 'public', False, 'set changeset phase to public'),
+   ...,
+   ('r', 'rev', [], 'target revision', 'REV')],
+ '[-p|-d|-s] [-f] [-r] [REV...]'
+  )
+  sectionfunc: minirst function to format command category headers
+  subsectionfunc: minirst function to format command headers
+"""
 h = {}
 for c, attr in cmdtable.items():
 f = c.split(b"|")[0]
@@ -222,7 +243,7 @@
 if f.startswith(b"debug"):
 continue
 d = get_cmd(h[f], cmdtable)
-ui.write(sectionfunc(d[b'cmd']))
+ui.write(subsectionfunc(d[b'cmd']))
 # short description
 ui.write(d[b'desc'][0])
 # synopsis



To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6327: gendoc: guarantee that all commands were processed.

[Sietse (Sietse Brouwer)]

Sietse updated this revision to Diff 14990.
Sietse retitled this revision from "gendoc: guarantee that all commands were 
processed" to "gendoc: guarantee that all commands were processed.".

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6327?vs=14960&id=14990

REVISION DETAIL
  https://phab.mercurial-scm.org/D6327

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -194,13 +194,21 @@
 helpcategory = details[0].helpcategory
 return helpcategory or help.registrar.command.CATEGORY_NONE
 
+cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
+for cmd in cmds:
+try:
+cmdsbycategory[helpcategory(cmd)].append(cmd)
+except KeyError:
+# If a command category wasn't registered, the command won't get
+# rendered below, so we raise an AssertionError.
+raise AssertionError(
+"The following command did not register its (category) in "
+"help.CATEGORY_ORDER: %s (%s)" % (cmd, helpcategory(cmd))
+)
+
 # Print the help for each command. We present the commands grouped by
 # category, and we use help.CATEGORY_ORDER as a guide for a helpful order
 # in which to present the categories.
-cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
-for cmd in cmds:
-cmdsbycategory[helpcategory(cmd)].append(cmd)
-
 for category in help.CATEGORY_ORDER:
 categorycmds = cmdsbycategory[category]
 if not categorycmds:
@@ -249,7 +257,6 @@
 if d[b'aliases']:
 ui.write(_(b"aliases: %s\n\n") % b" ".join(d[b'aliases']))
 
-
 def allextensionnames():
 return set(extensions.enabled().keys()) | set(extensions.disabled().keys())
 



To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6326: gendoc: group commands by category in man page and HTML help

[Sietse (Sietse Brouwer)]

Sietse updated this revision to Diff 14989.
Sietse edited the summary of this revision.

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D6326?vs=14959&id=14989

REVISION DETAIL
  https://phab.mercurial-scm.org/D6326

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -185,8 +185,32 @@
 h[f] = c
 cmds = h.keys()
 
-if True:
-for f in sorted(cmds):
+def helpcategory(cmd, h=h, cmdtable=cmdtable):
+"""Given a canonical command name from `cmds` (above), retrieve its
+help category. If helpcategory is None, default to CATEGORY_NONE
+"""
+fullname = h[cmd]
+details = cmdtable[fullname]
+helpcategory = details[0].helpcategory
+return helpcategory or help.registrar.command.CATEGORY_NONE
+
+# Print the help for each command. We present the commands grouped by
+# category, and we use help.CATEGORY_ORDER as a guide for a helpful order
+# in which to present the categories.
+cmdsbycategory = {category: [] for category in help.CATEGORY_ORDER}
+for cmd in cmds:
+cmdsbycategory[helpcategory(cmd)].append(cmd)
+
+for category in help.CATEGORY_ORDER:
+categorycmds = cmdsbycategory[category]
+if not categorycmds:
+continue  # Skip empty categories
+# Print a section header for the category.
+# For now, the category header is at the same level as the headers for
+# the commands in the category; this is fixed in the next commit.
+ui.write(sectionfunc(help.CATEGORY_NAMES[category]))
+# Print each command in the category
+for f in sorted(categorycmds):
 if f.startswith(b"debug"):
 continue
 d = get_cmd(h[f], cmdtable)



To: Sietse, #hg-reviewers, martinvonz
Cc: martinvonz, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6332: releasenotes: add a file in which to record release notes

[Sietse (Sietse Brouwer)]

Sietse added a comment.


  I think this is a fine idea -- it is more robust, because it does not depend 
on getting the commit syntax right, but on knowing the right place. It also 
means commit messages (for developers, one per commit) don't have to do double 
duty as release notes (for users, one per functional change).
  
  When this patch is accepted, one could make this policy visible by adding an 
"Update release notes" section to the 
https://www.mercurial-scm.org/wiki/ContributingChanges checklist.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6332

To: martinvonz, #hg-reviewers
Cc: Sietse, mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6329: gendoc: nest command headers under category headers

[Sietse (Sietse Brouwer)]

Sietse added a comment.


  Changing this script affects hg.1 and hg.1.html. I have uploaded the original 
output, and the output after this patch stack; links below.
  
  hg.1:
  
  - (original) F286175: 1-original-hg.1 
  - (by category, with nested headers) F286176: 6-nestedheaders-hg.1 

  
  hg.1.html:
  
  - (original) F286177: 1-original-hg.1.html 
 (original)
  - (by category, with nested headers) F286178: 6-nestedheaders-hg.1.html 


REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6329

To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6329: gendoc: nest command headers under category headers

[Sietse (Sietse Brouwer)]

Sietse created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6329

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -120,7 +120,7 @@
 
 # print cmds
 ui.write(minirst.section(_(b"Commands")))
-commandprinter(ui, table, minirst.subsection)
+commandprinter(ui, table, minirst.subsection, minirst.subsubsection)
 
 # print help topics
 # The config help topic is included in the hgrc.5 man page.
@@ -143,7 +143,8 @@
 cmdtable = getattr(mod, 'cmdtable', None)
 if cmdtable:
 ui.write(minirst.subsubsection(_(b'Commands')))
-commandprinter(ui, cmdtable, minirst.subsubsubsection)
+commandprinter(ui, cmdtable, minirst.subsubsubsection,
+minirst.subsubsubsubsection)
 
 def showtopic(ui, topic):
 extrahelptable = [
@@ -177,7 +178,27 @@
 ui.write(doc)
 ui.write(b"\n")
 
-def commandprinter(ui, cmdtable, sectionfunc):
+def commandprinter(ui, cmdtable, sectionfunc, subsectionfunc):
+"""Render restructuredtext describing a list of commands and their
+documentations, grouped by command category.
+
+Args:
+  ui: UI object to write the output to
+  cmdtable: a dict that maps a string of the command name plus its aliases
+(separated with pipes) to a 3-tuple of (the command's function, a list
+of its option descriptions, and a string summarizing available
+options). Example, with aliases added for demonstration purposes:
+
+  'phase|alias1|alias2': (
+ ,
+ [ ('p', 'public', False, 'set changeset phase to public'),
+   ...,
+   ('r', 'rev', [], 'target revision', 'REV')],
+ '[-p|-d|-s] [-f] [-r] [REV...]'
+  )
+  sectionfunc: minirst function to format command category headers
+  subsectionfunc: minirst function to format command headers
+"""
 h = {}
 for c, attr in cmdtable.items():
 f = c.split(b"|")[0]
@@ -213,18 +234,16 @@
 categorycmds = sorted([
 cmd for cmd in cmds
 if helpcategory(cmd) == category])
-# Print a section header for the category. Skip empty categories. For
-# now, the category header is at the same level as the headers for the
-# commands in the category; this is fixed in the next commit.
+# Print a section header for the category. Skip empty categories.
 if categorycmds:
 ui.write(sectionfunc(help.CATEGORY_NAMES[category]))
 # Print each command in the category
 for f in sorted(categorycmds):
 if f.startswith(b"debug"):
 continue
 processedcmds.append(f)  # log command
 d = get_cmd(h[f], cmdtable)
-ui.write(sectionfunc(d[b'cmd']))
+ui.write(subsectionfunc(d[b'cmd']))
 # short description
 ui.write(d[b'desc'][0])
 # synopsis



To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6328: minirst: support subsubsubsubsections (header level 5) with marker ''''

[Sietse (Sietse Brouwer)]

Sietse created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6328

AFFECTED FILES
  mercurial/minirst.py

CHANGE DETAILS

diff --git a/mercurial/minirst.py b/mercurial/minirst.py
--- a/mercurial/minirst.py
+++ b/mercurial/minirst.py
@@ -44,6 +44,9 @@
 def subsubsubsection(s):
 return "%s\n%s\n\n" % (s, "." * encoding.colwidth(s))
 
+def subsubsubsubsection(s):
+return "%s\n%s\n\n" % (s, "'" * encoding.colwidth(s))
+
 def replace(text, substs):
 '''
 Apply a list of (find, replace) pairs to a text.



To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6327: gendoc: guarantee that all commands were processed.

[Sietse (Sietse Brouwer)]

Sietse created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REVISION SUMMARY
  The new logic renders the commands belonging to each category in turn.
  Commands with an unregistered category are at risk of getting skipped
  because their category is not in the list. By comparing the list of all
  commands to a log of processed commands, we can detect commands with
  unregistered categories and fail with an error message.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6327

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -196,6 +196,12 @@
 return help.registrar.command.CATEGORY_NONE
 return helpcategory
 
+# Keep a log of processed commands. If a command category isn't registered
+# in help.CATEGORY_ORDER, the command doesn't get processed by
+# commandprinter. By comparing the list of processed commands to the
+# original list of commands, we can detect unregistered categories.
+processedcmds = []
+
 # Print the help for each command. We present the commands grouped by
 # category, and we use help.CATEGORY_ORDER as a guide for a helpful order
 # in which to present the categories.
@@ -216,6 +222,7 @@
 for f in sorted(categorycmds):
 if f.startswith(b"debug"):
 continue
+processedcmds.append(f)  # log command
 d = get_cmd(h[f], cmdtable)
 ui.write(sectionfunc(d[b'cmd']))
 # short description
@@ -251,7 +258,17 @@
 # aliases
 if d[b'aliases']:
 ui.write(_(b"aliases: %s\n\n") % b" ".join(d[b'aliases']))
-
+# Make sure that we left no commands unprocessed.
+expected = sorted(filter(lambda c: not c.startswith('debug'), cmds))
+observed = sorted(processedcmds)
+if not observed == expected:
+unprocessed = sorted(set(expected) - set(observed))
+unprocessedinfo = ', '.join(
+"%s (%s)" % (cmd, helpcategory(cmd))
+for cmd in unprocessed
+)
+raise AssertionError("The following commands did not register their"
+" (category) in help.CATEGORY_ORDER: %s" % unprocessedinfo)
 
 def allextensionnames():
 return set(extensions.enabled().keys()) | set(extensions.disabled().keys())



To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6326: gendoc: group commands by category in man page and HTML help

[Sietse (Sietse Brouwer)]

Sietse created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REVISION SUMMARY
  Make Mercurial's man page and HTML help group commands by category, and
  present the categories in a helpful order. `hg help` already does this;
  this patch uses the same metadata.
  
  This patch uses the same header level for command categories, and for
  commands. A subsequent patch will push the command headers down one
  level.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6326

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -185,8 +185,35 @@
 h[f] = c
 cmds = h.keys()
 
-if True:
-for f in sorted(cmds):
+def helpcategory(cmd, h=h, cmdtable=cmdtable):
+"""Given a canonical command name from `cmds` (above), retrieve its
+help category. If helpcategory is None, default to CATEGORY_NONE
+"""
+fullname = h[cmd]
+details = cmdtable[fullname]
+helpcategory = details[0].helpcategory
+if helpcategory is None:
+return help.registrar.command.CATEGORY_NONE
+return helpcategory
+
+# Print the help for each command. We present the commands grouped by
+# category, and we use help.CATEGORY_ORDER as a guide for a helpful order
+# in which to present the categories.
+for category in help.CATEGORY_ORDER:
+# Make a list of the commands in this category.
+# Rescanning the list of all commands for each category is quadratic;
+# this is justified because N is low, and repeating the lookup keeps
+# our data structure simpler.
+categorycmds = sorted([
+cmd for cmd in cmds
+if helpcategory(cmd) == category])
+# Print a section header for the category. Skip empty categories. For
+# now, the category header is at the same level as the headers for the
+# commands in the category; this is fixed in the next commit.
+if categorycmds:
+ui.write(sectionfunc(help.CATEGORY_NAMES[category]))
+# Print each command in the category
+for f in sorted(categorycmds):
 if f.startswith(b"debug"):
 continue
 d = get_cmd(h[f], cmdtable)



To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6325: gendoc: indent loop to make next patch more legible

[Sietse (Sietse Brouwer)]

Sietse created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6325

AFFECTED FILES
  doc/gendoc.py

CHANGE DETAILS

diff --git a/doc/gendoc.py b/doc/gendoc.py
--- a/doc/gendoc.py
+++ b/doc/gendoc.py
@@ -185,44 +185,45 @@
 h[f] = c
 cmds = h.keys()
 
-for f in sorted(cmds):
-if f.startswith(b"debug"):
-continue
-d = get_cmd(h[f], cmdtable)
-ui.write(sectionfunc(d[b'cmd']))
-# short description
-ui.write(d[b'desc'][0])
-# synopsis
-ui.write(b"::\n\n")
-synopsislines = d[b'synopsis'].splitlines()
-for line in synopsislines:
-# some commands (such as rebase) have a multi-line
+if True:
+for f in sorted(cmds):
+if f.startswith(b"debug"):
+continue
+d = get_cmd(h[f], cmdtable)
+ui.write(sectionfunc(d[b'cmd']))
+# short description
+ui.write(d[b'desc'][0])
 # synopsis
-ui.write(b"   %s\n" % line)
-ui.write(b'\n')
-# description
-ui.write(b"%s\n\n" % d[b'desc'][1])
-# options
-opt_output = list(d[b'opts'])
-if opt_output:
-opts_len = max([len(line[0]) for line in opt_output])
-ui.write(_(b"Options:\n\n"))
-multioccur = False
-for optstr, desc in opt_output:
-if desc:
-s = b"%-*s  %s" % (opts_len, optstr, desc)
-else:
-s = optstr
-ui.write(b"%s\n" % s)
-if optstr.endswith(b"[+]>"):
-multioccur = True
-if multioccur:
-ui.write(_(b"\n[+] marked option can be specified"
-   b" multiple times\n"))
-ui.write(b"\n")
-# aliases
-if d[b'aliases']:
-ui.write(_(b"aliases: %s\n\n") % b" ".join(d[b'aliases']))
+ui.write(b"::\n\n")
+synopsislines = d[b'synopsis'].splitlines()
+for line in synopsislines:
+# some commands (such as rebase) have a multi-line
+# synopsis
+ui.write(b"   %s\n" % line)
+ui.write(b'\n')
+# description
+ui.write(b"%s\n\n" % d[b'desc'][1])
+# options
+opt_output = list(d[b'opts'])
+if opt_output:
+opts_len = max([len(line[0]) for line in opt_output])
+ui.write(_(b"Options:\n\n"))
+multioccur = False
+for optstr, desc in opt_output:
+if desc:
+s = b"%-*s  %s" % (opts_len, optstr, desc)
+else:
+s = optstr
+ui.write(b"%s\n" % s)
+if optstr.endswith(b"[+]>"):
+multioccur = True
+if multioccur:
+ui.write(_(b"\n[+] marked option can be specified"
+   b" multiple times\n"))
+ui.write(b"\n")
+# aliases
+if d[b'aliases']:
+ui.write(_(b"aliases: %s\n\n") % b" ".join(d[b'aliases']))
 
 
 def allextensionnames():



To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

D6324: help: register the 'gpg' command category and give it a description

[Sietse (Sietse Brouwer)]

Sietse created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REVISION SUMMARY
  help.py expects extensions to register their command category in the
  CATEGORY_ORDER and CATEGORY_NAMES variables. Once gendoc.py orders
  commands by category, in the next patch, it'll assume this registration
  (and raise an exception on encountering any unregistered categories).
  Luckily, gpg is the only bundled extension with an unregistered custom
  category, so let's fix it.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D6324

AFFECTED FILES
  hgext/gpg.py

CHANGE DETAILS

diff --git a/hgext/gpg.py b/hgext/gpg.py
--- a/hgext/gpg.py
+++ b/hgext/gpg.py
@@ -49,6 +49,11 @@
 
 # Custom help category
 _HELP_CATEGORY = 'gpg'
+help.CATEGORY_ORDER.insert(
+help.CATEGORY_ORDER.index(registrar.command.CATEGORY_HELP),
+_HELP_CATEGORY
+)
+help.CATEGORY_NAMES[_HELP_CATEGORY] = 'Signing changes (GPG)'
 
 class gpg(object):
 def __init__(self, path, key=None):



To: Sietse, #hg-reviewers
Cc: mercurial-devel
___
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel