[PATCH b4 0/4] Add the man page to the pip package

[PATCH b4 0/4] Add the man page to the pip package

[Philippe Blain]

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
-- 
2.27.0

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

[Philippe Blain]

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

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 5d6f10a..e0d7c2e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,4 @@ __pycache__
 *.patch
 *.mbx
 *.cover
+.venv
-- 
2.27.0

[PATCH b4 2/4] Link to the README from PyPI

[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.

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup.py b/setup.py
index ed24367..6ad18a3 100644
--- a/setup.py
+++ b/setup.py
@@ -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',
-- 
2.27.0

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

[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.

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
 README.rst   | 3 ++-
 man/b4.5     | 3 ++-
 man/b4.5.rst | 3 ++-
 setup.py     | 3 +++
 4 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/README.rst b/README.rst
index 99fa339..274cf0e 100644
--- a/README.rst
+++ b/README.rst
@@ -33,4 +33,5 @@ Setting up a symlink should also be possible.
 Support
 -------
 For support or with any other questions, please email
-tools@linux.kernel.org.
+tools@linux.kernel.org, or browse the list archive at
+https://linux.kernel.org/g/tools.
diff --git a/man/b4.5 b/man/b4.5
index cdbd1d0..cc8bddf 100644
--- a/man/b4.5
+++ b/man/b4.5
@@ -402,7 +402,8 @@ Default configuration, with explanations:
 .UNINDENT
 .SH SUPPORT
 .sp
-Please email \fI\%tools@linux.kernel.org\fP with support requests.
+Please email \fI\%tools@linux.kernel.org\fP with support requests,
+or browse the list archive at \fI\%https://linux.kernel.org/g/tools\fP\&.
 .SH AUTHOR
 mricon@kernel.org
 
diff --git a/man/b4.5.rst b/man/b4.5.rst
index 9e0d995..2e1f5b0 100644
--- a/man/b4.5.rst
+++ b/man/b4.5.rst
@@ -275,4 +275,5 @@ Default configuration, with explanations::
 
 SUPPORT
 -------
-Please email tools@linux.kernel.org with support requests.
+Please email tools@linux.kernel.org with support requests,
+or browse the list archive at https://linux.kernel.org/g/tools.
diff --git a/setup.py b/setup.py
index 6ad18a3..65ede59 100644
--- a/setup.py
+++ b/setup.py
@@ -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',
-- 
2.27.0

[PATCH b4 4/4] Distribute the manpage with the pip package

[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

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---

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(+)

diff --git a/setup.py b/setup.py
index 65ede59..867b5cf 100644
--- a/setup.py
+++ b/setup.py
@@ -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'
-- 
2.27.0

Re: [PATCH b4 0/4] Add the man page to the pip package

[Konstantin Ryabitsev]

On Thu, 12 Nov 2020 10:21:30 -0500, Philippe Blain wrote:
> 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,
-- 
Konstantin Ryabitsev <konstantin@linuxfoundation.org>