Skip to contentSkip to conversation

Add the man page to the pip package

PATCH Applied Philippe Blain 2 participants 6 messages Nov 12, 2020 – Nov 17, 2020

lore
Share & tools
lore
#0 lore raw

cover Add the man page to the pip package

Hi ! I'm a Git contributor and just discovered b4 yesterday. I'm already convinced it will be a great addition to my workflow.

I noticed that the man page is not installed when you 'pip install' the package, so patch 4/4 in this here series takes care of that.

The other 3 patches are project-level goodies that I thought were good additions. Feel free to drop them if you don't think so.

Cheers!

Philippe.

P.S. a quick search on https://lore.kernel.org/git/ reveals you did not formally announce neither b4 nor its predecessor get-lore-mbox there. I think it could be helpful for some Git folks too :)

Philippe Blain (4):
Add '.venv' to .gitignore
Link to the README from PyPI
Add pointers to https://linux.kernel.org/g/tools
Distribute the manpage with the pip package

 .gitignore   | 1 +
 README.rst   | 3 ++-
 man/b4.5     | 3 ++-
 man/b4.5.rst | 3 ++-
 setup.py     | 6 +++++-
 5 files changed, 12 insertions(+), 4 deletions(-)

base-commit: f33033c03cf96ed769289ebf6d3c26b0cf540683

Signature · 1 line
2.27.0
#1 lore raw

PATCH 1/4 Add '.venv' to .gitignore

When using the built-in Python3 module 'venv' to create a virtual environment, it is common to name the folder containing the virtual environment '.venv' [1].

To help developers wishing to use a virtual environment to develop the project, add '.venv' to the .gitignore file.

[1] https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)
.gitignore +1 -0
index 5d6f10a..e0d7c2e 100644
@@ -13,3 +13,4 @@ __pycache__
 *.patch
 *.mbx
 *.cover
+.venv
Signature · 1 line
2.27.0
#2 lore raw

PATCH 2/4 Link to the README from PyPI

In reply to Philippe Blain

Instead of linking to the default gitweb view ('summary'), link to the README in the 'tree' view, so that users coming from pypi.org can directly read it.

---
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
setup.py +1 -1
index ed24367..6ad18a3 100644
@@ -26,7 +26,7 @@ NAME = 'b4'
 
 setup(
     version=find_version('b4/__init__.py'),
-    url='https://git.kernel.org/pub/scm/utils/b4/b4.git',
+    url='https://git.kernel.org/pub/scm/utils/b4/b4.git/tree/README.rst',
     name=NAME,
     description='A tool to work with public-inbox and patch archives',
     author='Konstantin Ryabitsev',
Signature · 1 line
2.27.0
#3 lore raw

PATCH 3/4 Add pointers to https://linux.kernel.org/g/tools

In reply to Philippe Blain

Add links to the Groups.io instance at https://linux.kernel.org/g/tools
in the man page, the README and on PyPI.

---
 README.rst   | 3 ++-
 man/b4.5     | 3 ++-
 man/b4.5.rst | 3 ++-
 setup.py     | 3 +++
 4 files changed, 9 insertions(+), 3 deletions(-)
README.rst +2 -1
index 99fa339..274cf0e 100644
@@ -33,4 +33,5 @@ Setting up a symlink should also be possible.
 Support
 -------
 For support or with any other questions, please email
[email protected].
[email protected], or browse the list archive at
+https://linux.kernel.org/g/tools.
man/b4.5 +2 -1
index cdbd1d0..cc8bddf 100644
@@ -402,7 +402,8 @@ Default configuration, with explanations:
 .UNINDENT
 .SH SUPPORT
 .sp
-Please email \fI\%[email protected]\fP with support requests.
+Please email \fI\%[email protected]\fP with support requests,
+or browse the list archive at \fI\%https://linux.kernel.org/g/tools\fP\&.
 .SH AUTHOR
 [email protected]
 
man/b4.5.rst +2 -1
index 9e0d995..2e1f5b0 100644
@@ -275,4 +275,5 @@ Default configuration, with explanations::
 
 SUPPORT
 -------
-Please email [email protected] with support requests.
+Please email [email protected] with support requests,
+or browse the list archive at https://linux.kernel.org/g/tools.
setup.py +3 -0
index 6ad18a3..65ede59 100644
@@ -27,6 +27,9 @@ NAME = 'b4'
 setup(
     version=find_version('b4/__init__.py'),
     url='https://git.kernel.org/pub/scm/utils/b4/b4.git/tree/README.rst',
+    project_urls={
+        'Community': 'https://linux.kernel.org/g/tools'
+    },
     name=NAME,
     description='A tool to work with public-inbox and patch archives',
     author='Konstantin Ryabitsev',
Signature · 1 line
2.27.0
#4 lore raw

PATCH 4/4 Distribute the manpage with the pip package

In reply to Philippe Blain

The 'data_files' option to setuptools.setup can be used to install additional files "outside" of the package [1].

Use it so that the manpage is installed with the package.

Install the manpage to '$PREFIX/share/man/man5', mimicking what the Filesystem Hiararchy Standard mandates for the '/usr/local/' prefix [2].

Prefer '$PREFIX/share/man/man5' to '$PREFIX/man/man5' since the later is deprecated [3].

[1] https://docs.python.org/3/distutils/setupscript.html#installing-additional-files
[2] https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s11.html#idm236091648080
[3] https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s11.html#ftn.idm236091648080

---

Notes:
A small note: by installing the man page to '$PREFIX/share/man', we are unfortunately trusting every other package installed in '$PREFIX' to follow the same convention.

The reason is that when invoking man <cmd>, man(1) looks for the <cmd> man page by searching for man directories "near" the directory where <cmd> is found in 'PATH'. This search is limited to a single "nearby" directory and at least for some versions of man on some Linux distributions [1], '$PREFIX/man' is preferred to '$PREFIX/share/man'.

So if manpages exist in both locations, man will only look in '$PREFIX/man' and our manpage won't be found. The behavior of man(1) on macOS is the opposite; the search prefers '$PREFIX/share/man' to '$PREFIX/man' [2].

We could install the man page at both locations, but then we are wasting disk space (does it matter?). We can't easily use a symlink from one location to the other one, because this is not well supported by pip/setuptools [3].

[1] https://github.com/conda-forge/git-feedstock/pull/65#discussion_r322762265
[2] https://github.com/conda-forge/git-feedstock/issues/66#issuecomment-539095424
[3] https://github.com/pypa/pip/issues/5856

 setup.py | 1 +
 1 file changed, 1 insertion(+)
setup.py +1 -0
index 65ede59..867b5cf 100644
@@ -38,6 +38,7 @@ setup(
     license='GPLv2+',
     long_description=read('man/b4.5.rst'),
     long_description_content_type='text/x-rst',
+    data_files = [('share/man/man5', ['man/b4.5'])],
     keywords=['git', 'lore.kernel.org', 'patches'],
     install_requires=[
         'requests'
Signature · 1 line
2.27.0
#5 lore raw
In reply to Philippe Blain
Quoted 9 lines · Philippe Blain

I'm already convinced it will be a great addition to my workflow.

I noticed that the man page is not installed when you 'pip install' the package, so patch 4/4 in this here series takes care of that.

The other 3 patches are project-level goodies that I thought were good additions. Feel free to drop them if you don't think so.

[...]

Applied, thanks!

[1/4] Add '.venv' to .gitignore

      commit: 7804e65259d192a1c5bfaa49954d15be486646f7
[2/4] Link to the README from PyPI
      commit: fdd09fd76177a55ac67006057fac32b4a907c3f5
[3/4] Add pointers to https://linux.kernel.org/g/tools
      commit: dc5f193cb5db91279fbbb3a13c9e59e659afd39b
[4/4] Distribute the manpage with the pip package
      commit: cc6bbbeb1c824da64a59fbd1a483c780bc121c3b

Best regards,

Signature · 1 line
Konstantin Ryabitsev <[email protected]>