added arguments --min-version and --squash-patches

Author: marzer

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.17.0 - 2024-04-21
+
+-   added arguments `--min-version` and `--squash-patches` for more control over `--git-tags` mode
+
 ## v0.16.0 - 2024-01-28
 
 -   added multi-version mode argument `--git-tags`

README.md

@@ -69,14 +69,16 @@ Poxy is a command-line application.
 ```
 usage: poxy [-h] [-v] [--html | --no-html] [--ppinclude <regex>] [--ppexclude <regex>]
             [--theme {light,dark,custom}] [--threads N] [--version] [--xml | --no-xml]
-            [--werror | --no-werror] [--bug-report] [--git-tags] [config]
+            [--werror | --no-werror] [--bug-report] [--git-tags]
+            [--squash-patches | --no-squash-patches] [--min-version <version>]
+            [config]
 
   _ __   _____  ___   _
  | '_ \ / _ \ \/ / | | |
  | |_) | (_) >  <| |_| |
  | .__/ \___/_/\_\\__, |
  | |               __/ |
- |_|              |___/  v0.16.0 - github.com/marzer/poxy
+ |_|              |___/  v0.17.0 - github.com/marzer/poxy
 
 Generate fancy C++ documentation.
 
@@ -88,15 +90,22 @@ options:
   -v, --verbose         enable very noisy diagnostic output
   --html, --no-html     specify whether HTML output is required
   --ppinclude <regex>   pattern matching HTML file names to post-process (default: all)
-  --ppexclude <regex>   pattern matching HTML file names to exclude from post-processing (default: none)
+  --ppexclude <regex>   pattern matching HTML file names to exclude from post-processing (default: None)
   --theme {light,dark,custom}
                         sets the default visual theme (default: read from config)
   --threads N           set the number of threads to use (default: automatic)
   --version             print the version and exit
   --xml, --no-xml       specify whether XML output is required
-  --werror, --no-werror treat warnings as errors (default: read from config)
+  --werror, --no-werror
+                        treat warnings as errors (default: read from config)
   --bug-report          captures all output in a zip file for easier bug reporting.
   --git-tags            add git-tag-based semver version switcher to the generated HTML
+  --squash-patches, --no-squash-patches
+                        when using --git-tags and two version tags differ by a patch number,
+                        generate docs for the highest one only (default: True)
+  --min-version <version>
+                        sets the minimum version number to emit when using --git-tags,
+                        or a negative integer to mean "the last N versions". (default: None)
 ```
 
 The basic three-step to using Poxy is similar to Doxygen:

src/poxy/main.py

@@ -141,7 +141,7 @@ def multi_version_git_tags(args: argparse.Namespace):
     tags = sorted(tags, key=lambda t: t[1], reverse=True)
     tags.insert(0, (default_branch, (999999, 999999, 999999, 999999)))
 
-    if 0:
+    if args.squash_patches:
         # squash patch/rev differences
         seen_versions = set()
         for i in range(len(tags)):
@@ -152,14 +152,42 @@ def multi_version_git_tags(args: argparse.Namespace):
             seen_versions.add(normalized_version)
         tags = [t for t in tags if t]
 
+    if args.min_version is not None:
+        args.min_version = re.sub(r'[ \t]+', '', str(args.min_version).strip())
+        m = re.fullmatch(r'^[vV]?([0-9]+)(?:[.]([0-9]+)(?:[.]([0-9]+)(?:[.]([0-9]+))?)?)?$', args.min_version)
+        if m:
+            min_ver = (
+                (int(m[1] if m[1] else 0)),
+                (int(m[2] if m[2] else 0)),
+                (int(m[3] if m[3] else 0)),
+                (int(m[4] if m[4] else 0)),
+            )
+            tags = [t for t in tags if t[1] >= min_ver]
+        else:
+            try:
+                max_vers = int(args.min_version)
+                assert max_vers < 0
+                tags = tags[:-max_vers]
+            except:
+                raise Error(rf'min-version: expected semver tag or negative integer')
+
     tags = [t for t, _ in tags]
     print("Versions:")
     print("\n".join([rf'    {t}' for t in tags]))
 
     worker_args = [
         arg
         for arg in sys.argv[1:]
-        if arg not in (r'--bug-report', r'--git-tags', r'--worker', r'--versions-in-navbar', r'--verbose', r'-v')
+        if arg
+        not in (
+            r'--bug-report',
+            r'--git-tags',
+            r'--worker',
+            r'--versions-in-navbar',
+            r'--verbose',
+            r'-v',
+            r'--higest-patch-only',
+        )
     ]
     for key in (r'--output-dir', r'--temp-dir', r'--copy-config-to'):
         pos = -1
@@ -430,7 +458,7 @@ def main(invoker=True):
         type=str,
         default=None,
         metavar=r'<regex>',
-        help=r"pattern matching HTML file names to exclude from post-processing (default: none)",
+        help=r"pattern matching HTML file names to exclude from post-processing (default: %(default)s)",
     )
     args.add_argument(
         r'--theme',  #
@@ -456,6 +484,19 @@ def main(invoker=True):
     args.add_argument(
         r'--git-tags', action=r'store_true', help=r"add git-tag-based semver version switcher to the generated HTML"  #
     )
+    make_boolean_optional_arg(
+        args,
+        r'squash-patches',
+        default=True,
+        help='when using --git-tags and two version tags differ by a patch number,\ngenerate docs for the highest one only (default: %(default)s)',
+    )
+    args.add_argument(
+        r'--min-version',
+        type=str,
+        default=None,
+        metavar='<version>',
+        help='sets the minimum version number to emit when using --git-tags,\nor a negative integer to mean "the last N versions". (default: %(default)s)',
+    )
 
     # --------------------------------------------------------------
     # hidden/developer-only/deprecated/diagnostic arguments

src/poxy/version.txt

@@ -1 +1 @@
-0.16.0
+0.17.0