Merge #6555: backport: Merge bitcoin#24263: doc: Fix gen-manpages, re…

…write in Python

69b1328 Merge bitcoin#24263: doc: Fix gen-manpages, rewrite in Python (fanquake)

Pull request description:

  ## Issue being fixed or feature implemented
  gen-pages.sh doesn't work correctly for `dash-cli`, it removes all hyphens somehow:
  ```diff
   .IP
   Set a whitelist to filter incoming RPC calls for a specific user. The
   field <whitelist> comes in the format: <USERNAME>:<rpc 1>,<rpc
   2>,...,<rpc n>. If multiple whitelists are set for a given user,
  -they are set\-intersected. See \fB\-rpcwhitelistdefault\fR documentation
  +they are setintersected. See \fBrpcwhitelistdefault\fR documentation
   for information on default whitelist behavior.
   .HP
  ```

  ## What was done?
   - backport  bitcoin#24263

   Rewrite the manual page generation script in Python.

    This:
    - solves '-' stripping issue (fixes bitcoin#22681)
    - makes that a copyright footer is generated correctly again

    Also change the release process to swap gen-manpages and update RC steps, so that the pages will have the correct rc and/or final version.

  ## How Has This Been Tested?
  Produced correct documents for Dash Core v22.1: #6554

  ## Breaking Changes
  N/A

  ## Checklist:
  - [x] I have performed a self-review of my own code
  - [ ] I have commented my code, particularly in hard-to-understand areas
  - [ ] I have added or updated relevant unit/integration/functional/e2e tests
  - [ ] I have made corresponding changes to the documentation
  - [x] I have assigned this pull request to a milestone _(for repository code-owners and collaborators only)_

ACKs for top commit:
  PastaPastaPasta:
    utACK 69b1328; looks correct
  UdjinM6:
    utACK 69b1328
  kwvg:
    utACK 69b1328

Tree-SHA512: 01a7a9a8a4ba762e6ff36035a3fb554d998232d62da8c3441b12741e6a3b626c01c581c1ff3f6aa3dcac02e15d62eec7f2a7f94be9399895557cd0a7115424a7

contrib/devtools/README.md

@@ -76,7 +76,7 @@ year rather than two hyphenated years.
 If the file already has a copyright for `The Dash Core developers`, the
 script will exit.
 
-gen-manpages.sh
+gen-manpages.py
 ===============
 
 A small script to automatically create manpages in ../../doc/man by running the release binaries with the -help option.
@@ -87,7 +87,7 @@ repository. To use this tool with out-of-tree builds set `BUILDDIR`. For
 example:
 
 ```bash
-BUILDDIR=$PWD/build contrib/devtools/gen-manpages.sh
+BUILDDIR=$PWD/build contrib/devtools/gen-manpages.py
 ```
 
 github-merge.py

contrib/devtools/gen-manpages.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+# Copyright (c) 2022 The Bitcoin Core developers
+# Distributed under the MIT software license, see the accompanying
+# file COPYING or http://www.opensource.org/licenses/mit-license.php.
+import os
+import subprocess
+import sys
+import tempfile
+
+BINARIES = [
+'src/dashd',
+'src/dash-cli',
+'src/dash-tx',
+'src/dash-wallet',
+#'src/dash-util',
+'src/qt/dash-qt',
+]
+
+# Paths to external utilities.
+git = os.getenv('GIT', 'git')
+help2man = os.getenv('HELP2MAN', 'help2man')
+
+# If not otherwise specified, get top directory from git.
+topdir = os.getenv('TOPDIR')
+if not topdir:
+    r = subprocess.run([git, 'rev-parse', '--show-toplevel'], stdout=subprocess.PIPE, check=True, universal_newlines=True)
+    topdir = r.stdout.rstrip()
+
+# Get input and output directories.
+builddir = os.getenv('BUILDDIR', topdir)
+mandir = os.getenv('MANDIR', os.path.join(topdir, 'doc/man'))
+
+# Verify that all the required binaries are usable, and extract copyright
+# message in a first pass.
+copyright = None
+versions = []
+for relpath in BINARIES:
+    abspath = os.path.join(builddir, relpath)
+    try:
+        r = subprocess.run([abspath, '--version'], stdout=subprocess.PIPE, universal_newlines=True)
+    except IOError:
+        print(f'{abspath} not found or not an executable', file=sys.stderr)
+        sys.exit(1)
+    # take first line (which must contain version)
+    verstr = r.stdout.split('\n')[0]
+    # last word of line is the actual version e.g. v22.99.0-5c6b3d5b3508
+    verstr = verstr.split()[-1]
+    assert verstr.startswith('v')
+
+    # Only dash-qt prints the copyright message on --version, so store it specifically.
+    if relpath == 'src/qt/dash-qt':
+        copyright = r.stdout.split('\n')[1:]
+
+    versions.append((abspath, verstr))
+
+if any(verstr.endswith('-dirty') for (_, verstr) in versions):
+    print("WARNING: Binaries were built from a dirty tree.")
+    print('man pages generated from dirty binaries should NOT be committed.')
+    print('To properly generate man pages, please commit your changes (or discard them), rebuild, then run this script again.')
+    print()
+
+with tempfile.NamedTemporaryFile('w', suffix='.h2m') as footer:
+    # Create copyright footer, and write it to a temporary include file.
+    assert copyright
+    footer.write('[COPYRIGHT]\n')
+    footer.write('\n'.join(copyright).strip())
+    footer.flush()
+
+    # Call the binaries through help2man to produce a manual page for each of them.
+    for (abspath, verstr) in versions:
+        outname = os.path.join(mandir, os.path.basename(abspath) + '.1')
+        print(f'Generating {outname}…')
+        subprocess.run([help2man, '-N', '--version-string=' + verstr, '--include=' + footer.name, '-o', outname, abspath], check=True)

doc/release-process.md

@@ -2,7 +2,7 @@ Release Process
 ====================
 
 * [ ] Update translations, see [translation_process.md](https://github.com/dashpay/dash/blob/master/doc/translation_process.md#synchronising-translations).
-* [ ] Update manpages, see [gen-manpages.sh](https://github.com/dashpay/dash/blob/master/contrib/devtools/README.md#gen-manpagessh).
+* [ ] Update manpages (after rebuilding the binaries), see [gen-manpages.py](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagespy).
 
 Before every minor and major release: