bpo-14102: argparse: Add generate man page #1169

louisom · 2017-04-18T14:19:02Z

No description provided.

keszybz

This looks very nice. It didn't actually run the code, but it should be possible to do something like python3 -c 'import mymodule; mymodule.parser().print_manpage() from the build system without any fuss.

keszybz · 2017-04-18T19:57:07Z

Doc/library/argparse.rst

+
+.. method:: ArgumentParser.add_manpage_section(heading, description)
+
+    Adding new section to man page.


"Add a new section to the man page. This only has an effect if print_manpage is used."

keszybz · 2017-04-18T19:57:49Z

Doc/library/argparse.rst

+
+    Description of parameters:
+
+      * heading: title of the section, it will automatically convert to upper case


"the title of the section, it will be automatically converted to upper case"

keszybz · 2017-04-18T19:59:48Z

Doc/library/argparse.rst

+    Description of parameters:
+
+      * heading: title of the section, it will automatically convert to upper case
+      * description: description about this section


This should be called content. What is the format of this text? Raw TROFF? This should be documented.

keszybz · 2017-04-18T19:59:58Z

Doc/library/argparse.rst

+      * heading: title of the section, it will automatically convert to upper case
+      * description: description about this section
+
+Some example usage::


keszybz · 2017-04-18T20:00:22Z

Doc/library/argparse.rst

+
+Some example usage::
+
+>>> # Adding Copyright section


"Add a Copyright section"

keszybz · 2017-04-18T20:08:29Z

Lib/argparse.py

+        # no help; start on same line and add a final newline
+        if not action.help:
+            tup = self._current_indent, '', action_header
+            action_header = '%*s%s' % tup


Argh, why %-formatting here?

action_header = '{:{}}{}'.format('', self._current_indent, action_header)

keszybz · 2017-04-18T20:10:40Z

Lib/argparse.py

+        # short action name; start on the same line and pad two spaces
+        elif len(action_header) <= action_width:
+            tup = self._current_indent, '', action_width, action_header
+            action_header = '%*s%-*s  ' % tup


action_header = '{:{}}{:>{}}'.format('', self._current_indent, action_header, action_width)

Not sure if this is better or not, letting this be a longer line.

This code is from argparse itself.

keszybz · 2017-04-18T20:11:50Z

Lib/argparse.py

+        action_width = help_position - self._current_indent - 2
+        action_header = self._format_action_invocation(action)
+
+        # no help; start on same line and add a final newline


Those comments should be moved under the if, and then the whole if-ifelse-else does not need to be divided by empty lines.

keszybz · 2017-04-18T20:13:20Z

Lib/argparse.py

@@ -2345,6 +2491,11 @@ def format_help(self):
        # determine help from format above
        return formatter.format_help()

+    def format_manpage(self):
+        formatter = self._get_formatter()
+


Spurious empty line.

keszybz · 2017-04-18T20:13:48Z

Misc/NEWS

@@ -313,6 +313,8 @@ Extension Modules
 Library
 -------

+- bpo-14102: argparse now can generate Unix man page. Patch by Louie Lu.


"UNIX man pages"

codecov · 2017-04-19T03:38:27Z

Codecov Report

Merging #1169 into master will decrease coverage by 0.02%.
The diff coverage is 1.09%.

@@            Coverage Diff             @@
##           master    #1169      +/-   ##
==========================================
- Coverage   83.44%   83.42%   -0.03%     
==========================================
  Files        1367     1367              
  Lines      346017   346108      +91     
==========================================
+ Hits       288721   288727       +6     
- Misses      57296    57381      +85

Impacted Files	Coverage Δ
Lib/argparse.py	`77.91% <1.09%> (-5.9%)`	⬇️
Lib/test/test_logging.py	`94.98% <0%> (+0.04%)`	⬆️
Lib/heapq.py	`98.85% <0%> (+1.52%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d6d344d...34a1ac7. Read the comment docs.

[1] python/cpython#1169

merwok · 2018-02-19T00:56:15Z

Doc/library/argparse.rst

+    OPTIONS
+       optional arguments
+           -h, --help
+                  show this help message and exit


If this the real output? I would expect the command to print out the man page markup, so that it can be saved as a program.1 file and distributed by downstream packagers.

I see that the code does produce the markup as I expected!

It’s the example that’s missing something:

$ python myprogram.py --manpage | nroff -man ...

csabella · 2019-06-05T00:43:43Z

As this pull request has an 'unknown repository' for its branch, I'm going to close it. There is a lot of discussion for this issue on the bug tracker, so any replacement pull request should take all the open concerns into consideration.

bpo-14102: argparse: Add generate man page

87e2a7f

the-knights-who-say-ni added the CLA signed label Apr 18, 2017

keszybz reviewed Apr 18, 2017

View reviewed changes

Addressed keszybz problem

34a1ac7

louisom added 10 commits April 19, 2017 13:23

Make formatter format options' help text

f86f062

Fix unexpected newline

39f3bca

Remove unused comment

5ea4f12

Make metavar bold

173dde4

Remove header newline

966fb34

Fix error on subcommand

5a85ac5

Add unittest

1533bf3

Fix suppress showen

eee27fe

Update missing prog argument prevent differnet program name

81c1c82

Add command line action for manpage

9ec2e45

praiskup added a commit to praiskup/argparse-manpage that referenced this pull request Sep 24, 2017

Import some code from upstream proposal [1]

e588206

[1] python/cpython#1169

praiskup added a commit to praiskup/argparse-manpage that referenced this pull request Sep 24, 2017

Import some code from upstream proposal [1]

77fd5e4

[1] python/cpython#1169

praiskup mentioned this pull request Sep 26, 2017

Distribute the package in PyPI praiskup/argparse-manpage#3

Closed

Mariatta added needs rebase and removed needs rebase labels Oct 9, 2017

merwok reviewed Feb 19, 2018

View reviewed changes

brettcannon added the awaiting review label Feb 21, 2018

csabella closed this Jun 5, 2019

DanielWalsh mannequin mentioned this pull request Apr 10, 2022

argparse: add ability to create a man page #58310

Open

praiskup mentioned this pull request Apr 3, 2023

Incomplete man page of the copr-cli fedora-copr/copr#2634

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-14102: argparse: Add generate man page #1169

bpo-14102: argparse: Add generate man page #1169

louisom commented Apr 18, 2017

keszybz left a comment

keszybz Apr 18, 2017

keszybz Apr 18, 2017

keszybz Apr 18, 2017

keszybz Apr 18, 2017

keszybz Apr 18, 2017

keszybz Apr 18, 2017

keszybz Apr 18, 2017

louisom Apr 19, 2017

keszybz Apr 18, 2017

keszybz Apr 18, 2017

keszybz Apr 18, 2017

codecov bot commented Apr 19, 2017

merwok Feb 19, 2018 •

edited

Loading

merwok Jun 14, 2018

csabella commented Jun 5, 2019


		.. method:: ArgumentParser.add_manpage_section(heading, description)

		Adding new section to man page.


		Description of parameters:

		* heading: title of the section, it will automatically convert to upper case

bpo-14102: argparse: Add generate man page #1169

bpo-14102: argparse: Add generate man page #1169

Conversation

louisom commented Apr 18, 2017

keszybz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Apr 19, 2017

Codecov Report

merwok Feb 19, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csabella commented Jun 5, 2019

merwok Feb 19, 2018 •

edited

Loading