scripts/gendocs.py: make it work

remove unused html_write function

gendocs: update developer docs

docs/development.rst

@@ -360,8 +360,8 @@ for easier use by packagers downstream.
 When a command is added, a command line flag changed, added or removed,
 the usage docs need to be rebuilt as well::
 
-  python setup.py build_usage
-  python setup.py build_man
+  python scripts/gendocs.py build_usage
+  python scripts/gendocs.py build_man
 
 However, we prefer to do this as part of our :ref:`releasing`
 preparations, so it is generally not necessary to update these when
@@ -450,8 +450,12 @@ Checklist:
 - Update ``CHANGES.rst``, based on ``git log $PREVIOUS_RELEASE..``.
 - Check version number of upcoming release in ``CHANGES.rst``.
 - Render ``CHANGES.rst`` via ``make html`` and check for markup errors.
-- Verify that ``MANIFEST.in`` and ``setup.py`` are complete.
-- ``python setup.py build_usage ; python setup.py build_man`` and commit.
+- Verify that ``MANIFEST.in``, ``pyproject.toml`` and ``setup.py`` are complete.
+- Run these commands and commit::
+
+  python scripts/gendocs.py build_usage
+  python scripts/gendocs.py build_man
+
 - Tag the release::
 
     git tag -s -m "tagged/signed release X.Y.Z" X.Y.Z

docs/usage.rst

@@ -42,6 +42,7 @@ Usage
    usage/rcompress
    usage/rdelete
    usage/serve
+   usage/version
    usage/compact
    usage/config
    usage/lock

docs/usage/version.rst

@@ -0,0 +1 @@
+.. include:: version.rst.inc

docs/usage/version.rst.inc

@@ -0,0 +1,60 @@
+.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
+
+.. _borg_version:
+
+borg version
+------------
+.. code-block:: none
+
+    borg [common options] version [options]
+
+.. only:: html
+
+    .. class:: borg-options-table
+
+    +-------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                        |
+    |                                                       |
+    | :ref:`common_options`                                 |
+    +-------------------------------------------------------+
+
+    .. raw:: html
+
+        <script type='text/javascript'>
+        $(document).ready(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. only:: latex
+
+
+
+    :ref:`common_options`
+        |
+
+Description
+~~~~~~~~~~~
+
+This command displays the borg client version / borg server version.
+
+If a local repo is given, the client code directly accesses the repository,
+thus we show the client version also as the server version.
+
+If a remote repo is given (e.g. ssh:), the remote borg is queried and
+its version is displayed as the server version.
+
+Examples::
+
+    # local repo (client uses 1.4.0 alpha version)
+    $ borg version /mnt/backup
+    1.4.0a / 1.4.0a
+
+    # remote repo (client uses 1.4.0 alpha, server uses 1.2.7 release)
+    $ borg version ssh://borg@borgbackup:repo
+    1.4.0a / 1.2.7
+
+Due to the version tuple format used in borg client/server negotiation, only
+a simplified version is displayed (as provided by borg.version.format_version).
+
+There is also borg --version to display a potentially more precise client version.

scripts/gendocs.py

@@ -9,8 +9,6 @@ from collections import OrderedDict
 from datetime import datetime, timezone
 import time
 
-from setuptools import Command
-
 
 def format_metavar(option):
     if option.nargs in ("*", "..."):
@@ -23,16 +21,8 @@ def format_metavar(option):
         raise ValueError(f"Can't format metavar {option.metavar}, unknown nargs {option.nargs}!")
 
 
-class build_usage(Command):
-    description = "generate usage for each command"
-
-    user_options = [("output=", "O", "output directory")]
-
-    def initialize_options(self):
-        pass
-
-    def finalize_options(self):
-        pass
+class BuildUsage:
+    """generate usage docs for each command"""
 
     def run(self):
         print("generating usage docs")
@@ -49,6 +39,7 @@ class build_usage(Command):
         # borgfs_parser = Archiver(prog='borgfs').build_parser()
 
         self.generate_level("", parser, Archiver)
+        return 0
 
     def generate_level(self, prefix, parser, Archiver, extra_choices=None):
         is_subcommand = False
@@ -123,10 +114,6 @@ class build_usage(Command):
         # HTML output:
         # A table using some column-spans
 
-        def html_write(s):
-            for line in s.splitlines():
-                fp.write("    " + line + "\n")
-
         rows = []
         for group in parser._action_groups:
             if group.title == "Common options":
@@ -265,10 +252,8 @@ class build_usage(Command):
             fp.write(indent + option.ljust(padding) + desc + "\n")
 
 
-class build_man(Command):
-    description = "build man pages"
-
-    user_options = []
+class BuildMan:
+    """build man pages"""
 
     see_also = {
         "create": ("delete", "prune", "check", "patterns", "placeholders", "compression", "rcreate"),
@@ -308,12 +293,6 @@ class build_man(Command):
         "umount": "mount",
     }
 
-    def initialize_options(self):
-        pass
-
-    def finalize_options(self):
-        pass
-
     def run(self):
         print("building man pages (in docs/man)", file=sys.stderr)
         import borg
@@ -329,6 +308,7 @@ class build_man(Command):
         self.generate_level("", parser, Archiver, {"borgfs": borgfs_parser})
         self.build_topic_pages(Archiver)
         self.build_intro_page()
+        return 0
 
     def generate_level(self, prefix, parser, Archiver, extra_choices=None):
         is_subcommand = False
@@ -548,3 +528,33 @@ class build_man(Command):
 
         for option, desc in opts.items():
             write(option.ljust(padding), desc)
+
+
+def usage():
+    print(
+        textwrap.dedent(
+            """
+        Usage:
+            python scripts/gendocs.py build_usage  # build usage documentation
+            python scripts/gendocs.py build_man    # build man pages
+    """
+        )
+    )
+
+
+def main(argv):
+    if len(argv) < 2 or len(argv) == 2 and argv[1] in ("-h", "--help"):
+        usage()
+        return 0
+    command = argv[1]
+    if command == "build_usage":
+        return BuildUsage().run()
+    if command == "build_man":
+        return BuildMan().run()
+    usage()
+    return 1
+
+
+if __name__ == "__main__":
+    rc = main(sys.argv)
+    sys.exit(rc)