From b64f6e3335214ea8c1c4a9c744d7e0e775f8f20e Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Mon, 29 Jan 2024 20:26:33 +0100 Subject: [PATCH] scripts/gendocs.py: make it work remove unused html_write function gendocs: update developer docs --- docs/development.rst | 12 +++++--- docs/usage.rst | 1 + docs/usage/version.rst | 1 + docs/usage/version.rst.inc | 60 ++++++++++++++++++++++++++++++++++++ scripts/gendocs.py | 62 ++++++++++++++++++++++---------------- 5 files changed, 106 insertions(+), 30 deletions(-) create mode 100644 docs/usage/version.rst create mode 100644 docs/usage/version.rst.inc diff --git a/docs/development.rst b/docs/development.rst index 54b973b7..97976bb7 100644 --- a/docs/development.rst +++ b/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 diff --git a/docs/usage.rst b/docs/usage.rst index 658a40df..c27e4180 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -42,6 +42,7 @@ Usage usage/rcompress usage/rdelete usage/serve + usage/version usage/compact usage/config usage/lock diff --git a/docs/usage/version.rst b/docs/usage/version.rst new file mode 100644 index 00000000..204afdbb --- /dev/null +++ b/docs/usage/version.rst @@ -0,0 +1 @@ +.. include:: version.rst.inc diff --git a/docs/usage/version.rst.inc b/docs/usage/version.rst.inc new file mode 100644 index 00000000..1964ebc1 --- /dev/null +++ b/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 + + + +.. 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. \ No newline at end of file diff --git a/scripts/gendocs.py b/scripts/gendocs.py index b0777be4..9e435a65 100644 --- a/scripts/gendocs.py +++ b/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)