Add man_skip_desc_subtitle

A configuration value to optionally skip printing the description
of a command as a subtitle when generating a manpage.
This commit addresses issue sphinx-doc#9430

Signed-off-by: Harumi Kuno <harumi.kuno@hpe.com>

doc/usage/configuration.rst

@@ -402,6 +402,11 @@ General configuration
 
    .. versionadded:: 1.7
 
+.. confval:: man_skip_desc_subtitle
+
+   If true, do not print out description as a subtitle in man page
+   documents. Default is ``False``.
+
 .. confval:: nitpicky
 
    If true, Sphinx will warn about *all* references where the target cannot be

sphinx/cmd/build.py

@@ -179,6 +179,10 @@ def get_parser() -> argparse.ArgumentParser:
                        const='no',
                        help=__('do not emit colored output (default: '
                                'auto-detect)'))
+    group.add_argument('-S', '--skip-subtitle', dest='skipsubtitle', action='store_const',
+                       const='yes', default='no',
+                       help=__('Skip subtitle (default: '
+                               'auto-detect)'))
     group.add_argument('-w', metavar='FILE', dest='warnfile',
                        help=__('write warnings (and errors) to given file'))
     group.add_argument('-W', action='store_true', dest='warningiserror',

sphinx/config.py

@@ -129,6 +129,7 @@ class Config:
         'needs_sphinx': (None, None, [str]),
         'needs_extensions': ({}, None, []),
         'manpages_url': (None, 'env', []),
+        'man_skip_desc_subtitle': (False, 'env', []),
         'nitpicky': (False, None, []),
         'nitpick_ignore': ([], None, []),
         'nitpick_ignore_regex': ([], None, []),

sphinx/writers/manpage.py

@@ -113,8 +113,9 @@ def __init__(self, document: nodes.document, builder: Builder) -> None:
     def header(self) -> str:
         tmpl = (".TH \"%(title_upper)s\" \"%(manual_section)s\""
                 " \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n"
-                ".SH NAME\n"
-                "%(title)s \\- %(subtitle)s\n")
+                ".SH NAME\n")
+        if (not self.config.man_skip_desc_subtitle):
+            tmpl += "%(title)s \\- %(subtitle)s\n"
         return tmpl % self._docinfo
 
     def visit_start_of_file(self, node: Element) -> None: