From 26be2d1a77fdf404b9061bc6f4a2e25d7e4cbab0 Mon Sep 17 00:00:00 2001 From: Harumi Kuno Date: Mon, 30 Aug 2021 01:43:06 -0700 Subject: [PATCH 1/4] skip empty description Don't print the description of a command as a subtitle when generating a manpage if the description is empty. This commit addresses sphinx-doc#9430 Signed-off-by: Harumi Kuno --- sphinx/writers/manpage.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/sphinx/writers/manpage.py b/sphinx/writers/manpage.py index 90f3accbfd7..29d93aa84f5 100644 --- a/sphinx/writers/manpage.py +++ b/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 self._docinfo['subtitle']: + tmpl += "%(title)s \\- %(subtitle)s\n" return tmpl % self._docinfo def visit_start_of_file(self, node: Element) -> None: From d0e014b4bcf6b39bb7ba915a95204ae2371e6f0f Mon Sep 17 00:00:00 2001 From: Harumi Kuno Date: Sun, 5 Sep 2021 17:42:03 -0700 Subject: [PATCH 2/4] Omit NAME section if blank description Also, update man page for configuration to document that if a blank description is entered, the "NAME" section is an empty string. Signed-off-by: Harumi Kuno --- doc/usage/configuration.rst | 2 ++ sphinx/writers/manpage.py | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 0ae9cd5dfc3..fecbe0bfe7a 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2331,6 +2331,8 @@ These options influence manual page output. *description* Description of the manual page. This is used in the NAME section. + Can be an empty string if you do not want to automatically generate + the NAME section. *authors* A list of strings with authors, or a single string. Can be an empty diff --git a/sphinx/writers/manpage.py b/sphinx/writers/manpage.py index 29d93aa84f5..12fc31281bc 100644 --- a/sphinx/writers/manpage.py +++ b/sphinx/writers/manpage.py @@ -112,10 +112,10 @@ def __init__(self, document: nodes.document, builder: Builder) -> None: # overwritten -- added quotes around all .TH arguments def header(self) -> str: tmpl = (".TH \"%(title_upper)s\" \"%(manual_section)s\"" - " \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n" - ".SH NAME\n") + " \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n") if self._docinfo['subtitle']: - tmpl += "%(title)s \\- %(subtitle)s\n" + tmpl += (".SH NAME\n" + "%(title)s \\- %(subtitle)s\n") return tmpl % self._docinfo def visit_start_of_file(self, node: Element) -> None: From 571929974ad048d4d6d0322686281e7e5185c13a Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 11 Sep 2021 18:47:24 +0900 Subject: [PATCH 3/4] Add a testcase for #9694 --- tests/test_build_manpage.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/tests/test_build_manpage.py b/tests/test_build_manpage.py index 3680d8651be..e2479e4de77 100644 --- a/tests/test_build_manpage.py +++ b/tests/test_build_manpage.py @@ -23,6 +23,9 @@ def test_all(app, status, warning): assert r'\fBprint \fP\fIi\fP\fB\en\fP' in content assert r'\fBmanpage\en\fP' in content + # heading (title + description) + assert r'sphinxtests \- Sphinx 0.6alpha1' in content + # term of definition list including nodes.strong assert '\n.B term1\n' in content assert '\nterm2 (\\fBstronged partially\\fP)\n' in content @@ -35,6 +38,15 @@ def test_all(app, status, warning): assert 'Footnotes' not in content +@pytest.mark.sphinx('man', testroot='basic', + confoverrides={'man_pages': [('index', 'title', None, [], 1)]}) +def test_man_pages_empty_description(app, status, warning): + app.builder.build_all() + + content = (app.outdir / 'title.1').read_text() + assert r'title \-' not in content + + @pytest.mark.sphinx('man', testroot='basic', confoverrides={'man_make_section_directory': True}) def test_man_make_section_directory(app, status, warning): From fb141c355fe0b6c163074dd3b48c65a694421b6a Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 11 Sep 2021 18:54:29 +0900 Subject: [PATCH 4/4] Update CHANGES for PR #9594 --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index 4e98b2c8ab4..0e7c015f0df 100644 --- a/CHANGES +++ b/CHANGES @@ -17,6 +17,7 @@ Features added * #9479: autodoc: Emit a warning if target is a mocked object * #9447: html theme: Expose the version of Sphinx in the form of tuple as a template variable ``sphinx_version_tuple`` +* #9594: manpage: Suppress the title of man page if description is empty * #9445: py domain: ``:py:property:`` directive supports ``:classmethod:`` option to describe the class property * #9524: test: SphinxTestApp can take ``builddir`` as an argument