poxy 0.15.0__py3-none-any.whl → 0.17.0__py3-none-any.whl

poxy/css/poxy-overrides.css

@@ -26,7 +26,7 @@ body > header {
 	top: 0;
 	left: 0;
 	right: 0;
-	z-index: 5;
+	z-index: 6;
 }
 
 body > main {

poxy/generated/poxy.css

@@ -2638,7 +2638,7 @@ color: var(--color);
 html { height: 100%; scroll-padding-top: 4em; }
 body { min-height: 100%; }
 body { display: flex; flex-direction: column; }
-body > header { position: sticky; top: 0; left: 0; right: 0; z-index: 5; }
+body > header { position: sticky; top: 0; left: 0; right: 0; z-index: 6; }
 body > main { flex: 1 0 auto; }
 body > footer { flex-shrink: 0; }
 body > header,

poxy/main.py

@@ -10,9 +10,15 @@ The various entry-point methods used when poxy is invoked from the command line.
 import argparse
 import datetime
 import os
+import shutil
 import subprocess
 import sys
+import typing
 import zipfile
+from pathlib import Path
+
+import colorama
+from colorama import Fore, Style
 
 from . import css, doxygen, emoji, graph, mcss, paths
 from .run import run
@@ -22,10 +28,11 @@ from .version import *
 
 
 def _invoker(func, **kwargs):
+    colorama.init()
     try:
         func(**kwargs)
     except WarningTreatedAsError as err:
-        print(rf'Error: {err} (warning treated as error)', file=sys.stderr)
+        print(rf'{Style.BRIGHT}{Fore.RED}error:{Style.RESET_ALL} {err} (warning treated as error)', file=sys.stderr)
         sys.exit(1)
     except graph.GraphError as err:
         print_exception(err, include_type=True, include_traceback=True, skip_frames=1)
@@ -34,17 +41,17 @@ def _invoker(func, **kwargs):
         print(err, file=sys.stderr)
         sys.exit(1)
     except Error as err:
-        print(rf'Error: {err}', file=sys.stderr)
+        print(rf'{Style.BRIGHT}{Fore.RED}error:{Style.RESET_ALL} {err}', file=sys.stderr)
         sys.exit(1)
     except Exception as err:
-        print('\n*************\n', file=sys.stderr)
+        print(f'\n{Fore.RED}*************{Style.RESET_ALL}\n', file=sys.stderr)
         print_exception(err, include_type=True, include_traceback=True, skip_frames=1)
         print(
-            '*************\n'
+            f'{Fore.RED}*************\n'
             '\nYou appear to have triggered an internal bug!'
             '\nPlease re-run poxy with --bug-report and file an issue at github.com/marzer/poxy/issues'
             '\nMany thanks!'
-            '\n\n*************',
+            f'\n\n*************{Style.RESET_ALL}',
             file=sys.stderr,
         )
         sys.exit(1)
@@ -66,42 +73,309 @@ def make_boolean_optional_arg(args, name, default, help='', **kwargs):
         args.set_defaults(**{name: default})
 
 
-def bug_report():
-    BUG_REPORT_STRIP_ARGS = (
-        r'--bug-report',
-        r'--bug-report-internal',
-        r'-v',
-        r'--verbose',
-        r'--color',
-        r'--no-color',
-        r'--colour',
-        r'--no-colour',
+def git(git_args: str, cwd=None) -> typing.Tuple[int, str, str]:
+    assert git_args is not None
+    proc = subprocess.run(
+        ['git'] + str(git_args).strip().split(),
+        capture_output=True,
+        cwd=str(Path.cwd() if cwd is None else cwd),
+        encoding='utf-8',
     )
+    return (proc.returncode, proc.stdout.strip() if proc.stdout else "", proc.stderr.strip() if proc.stderr else "")
+
+
+def git_failed(git_output: typing.Tuple[int, str, str], desc=''):
+    assert git_output is not None
+    message = rf"git command failed"
+    if desc:
+        message += rf': {desc}'
+    if git_output[0] != 0:  # return code
+        message += f'\n  {Style.BRIGHT}exit code:{Style.RESET_ALL}\n    {git_output[0]}'
+    if git_output[1]:  # stdout
+        message += f'\n  {Style.BRIGHT}stdout:{Style.RESET_ALL}\n'
+        message += "\n".join([rf'    {i.strip()}' for i in git_output[1].split('\n') if i.strip()])
+    if git_output[2]:  # stderr
+        message += f'\n  {Style.BRIGHT}stderr:{Style.RESET_ALL}\n'
+        message += "\n".join([rf'    {i.strip()}' for i in git_output[2].split('\n') if i.strip()])
+    raise Error(message)
+
+
+def git_failed_if_nonzero(git_output: typing.Tuple[int, str, str], desc=''):
+    if git_output[0] != 0:
+        git_failed(git_output, desc)
+    return git_output
+
+
+def multi_version_git_tags(args: argparse.Namespace):
+    print('Running in git-tags mode')
+
+    input_dir = args.config.resolve()
+    if input_dir.is_file():
+        input_dir = input_dir.parent
+
+    if git('diff-files --quiet', cwd=input_dir)[0] or git('diff --no-ext-diff --cached --quiet', cwd=input_dir)[0]:
+        raise Error(rf'repository has uncommitted changes')
+
+    print('Fetching...')
+    git_failed_if_nonzero(git('fetch --tags', cwd=input_dir))
+
+    current_branch = git_failed_if_nonzero(git('rev-parse --abbrev-ref HEAD', cwd=input_dir))[1]
+    print(rf'Current branch: {current_branch}')
+    original_branch = current_branch
+
+    default_branch = git_failed_if_nonzero(git('rev-parse --abbrev-ref origin/HEAD', cwd=input_dir))[1]
+    default_branch = default_branch.removeprefix(r'origin/')
+    print(rf'Default branch: {default_branch}')
+
+    tags = git_failed_if_nonzero(git('tag', cwd=input_dir))[1].splitlines()
+    tags = [(t, t.strip().upper().lstrip('V').lstrip()) for t in tags]
+    tags = [(t, v) for t, v in tags if v]
+    tags = [(t, re.sub(r'\s+', '', v)) for t, v in tags]
+    tags = [(t, re.fullmatch(r'[0-9]+([.][0-9]+([.][0-9]+([.][0-9]+)?)?)?', v)) for t, v in tags]
+    tags = [(t, v) for t, v in tags if v]
+    tags = [(t, v[0].split('.')) for t, v in tags]
+    tags = [
+        (t, (int(v[0]), int(v[1]) if len(v) > 1 else 0, int(v[2]) if len(v) > 2 else 0, int(v[3]) if len(v) > 3 else 0))
+        for t, v in tags
+    ]
+    tags = sorted(tags, key=lambda t: t[1], reverse=True)
+    tags.insert(0, (default_branch, (999999, 999999, 999999, 999999)))
+
+    if args.squash_patches:
+        # squash patch/rev differences
+        seen_versions = set()
+        for i in range(len(tags)):
+            normalized_version = (tags[i][1][0], tags[i][1][1])
+            if normalized_version in seen_versions:
+                tags[i] = None
+                continue
+            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',
+            r'--higest-patch-only',
+        )
+    ]
+    for key in (r'--output-dir', r'--temp-dir', r'--copy-config-to'):
+        pos = -1
+        try:
+            pos = worker_args.index(key)
+        except:
+            pass
+        if pos != -1:
+            worker_args.pop(pos)
+            worker_args.pop(pos)
+
+    tags_temp_dir = paths.TEMP / 'tags' / temp_dir_name_for(str(Path.cwd()))
+    delete_directory(tags_temp_dir)
+    tags_temp_dir.mkdir(exist_ok=True, parents=True)
+
+    def cleanup():
+        nonlocal current_branch
+        nonlocal original_branch
+        nonlocal tags_temp_dir
+        nonlocal args
+        if not args.nocleanup:
+            delete_directory(tags_temp_dir)
+        if current_branch != original_branch:
+            print(rf'Switching back to {Style.BRIGHT}{original_branch}{Style.RESET_ALL}')
+            git_failed_if_nonzero(git(rf'checkout {original_branch}', cwd=input_dir))
+            current_branch = original_branch
+
+    emitted_tags = set()
+    with Defer(cleanup):
+        for tag in tags:
+            if current_branch != tag:
+                print(rf'Checking out {Style.BRIGHT}{tag}{Style.RESET_ALL}')
+                git_failed_if_nonzero(git(rf'checkout {tag}', cwd=input_dir))
+                current_branch = tag
+
+            if current_branch == default_branch:
+                git_failed_if_nonzero(git(rf'pull', cwd=input_dir))
+
+            output_dir = args.output_dir.resolve()
+            if tag != default_branch:
+                output_dir = tags_temp_dir / tag
+                output_dir.mkdir(exist_ok=True, parents=True)
+
+            try:
+                print(rf'Generating documentation for {Style.BRIGHT}{tag}{Style.RESET_ALL}')
+                result = subprocess.run(
+                    args=[
+                        r'poxy',
+                        r'--worker',
+                        r'--versions-in-navbar',
+                        r'--output-dir',
+                        str(output_dir),
+                        *worker_args,
+                    ],
+                    cwd=str(Path.cwd()),
+                    capture_output=not args.verbose,
+                    encoding='utf-8',
+                )
+                if result.returncode != 0:
+                    raise Error(
+                        rf'Poxy exited with code {result.returncode}{"" if args.verbose else " (re-run with --verbose to see worker output)"}'
+                    )
+            except Exception as exc:
+                msg = rf'documentation generation failed for {Style.BRIGHT}{tag}{Style.RESET_ALL}: {exc}'
+                if args.werror:
+                    raise WarningTreatedAsError(msg)
+                else:
+                    print(rf'{Style.BRIGHT}{Fore.YELLOW}warning:{Style.RESET_ALL} {msg}', file=sys.stderr)
+                    continue
+
+            if tag != default_branch:
+                source_dir = output_dir
+                output_dir = args.output_dir.resolve()
+                for src in ('html' if args.html else None, 'xml' if args.xml else None):
+                    if src is None:
+                        continue
+                    src = source_dir / src
+                    if not src.is_dir():
+                        continue
+                    dest = output_dir / src.name / tag
+                    dest.mkdir(exist_ok=True, parents=True)
+                    delete_directory(src / 'poxy')
+                    delete_file(src / 'poxy_changelog.html')
+                    delete_file(src / 'md_poxy_changelog.html')
+                    shutil.copytree(str(src), str(dest), dirs_exist_ok=True)
+                    if not args.nocleanup:
+                        delete_directory(src)
+
+            emitted_tags.add(tag)
+
+    if not args.html:
+        return
+
+    print("Linking versions in HTML output")
+    tags = [t for t in tags if t in emitted_tags]
+    html_root = args.output_dir.resolve() / 'html'
+    for tag in tags:
+        html_dir = html_root
+        if tag != default_branch:
+            html_dir /= tag
+        assert_existing_directory(html_dir)
+        for fp in get_all_files(html_dir, any=('*.css', '*.html', '*.js'), recursive=False):
+            text = read_all_text_from_file(fp)
+            if tag != default_branch:
+                text = text.replace('href="poxy/', 'href="../poxy/')
+                text = text.replace('href="poxy_changelog.html', 'href="../poxy_changelog.html')
+                text = text.replace('href="md_poxy_changelog.html', 'href="../md_poxy_changelog.html')
+                text = text.replace('src="poxy/', 'src="../poxy/')
+            versions = rf'<li class="poxy-navbar-version-selector"><a href="{fp.name}">Version: {"HEAD" if tag == default_branch else tag}</a><ol>'
+            for dest_tag in tags:
+                target = html_root
+                if dest_tag != default_branch:
+                    target /= dest_tag
+                assert target.is_dir()
+                target /= fp.name
+                if not target.is_file():
+                    target = target.parent / 'index.html'
+                assert target.is_file()
+                if tag == default_branch and dest_tag != default_branch:
+                    target = rf'{dest_tag}/{target.name}'
+                elif tag != default_branch and dest_tag == default_branch:
+                    target = rf'../{target.name}'
+                elif tag != dest_tag:
+                    target = rf'../{dest_tag}/{target.name}'
+                else:
+                    target = target.name
+                versions += (
+                    rf'<li><a href="{str(target)}">{"HEAD" if dest_tag == default_branch else dest_tag}</a></li>'
+                )
+            versions += rf'</ol></li>'
+            text = re.sub(
+                r'<li>\s*<span\s+class="poxy-navbar-version-selector"\s*>\s*FIXME\s*</span>\s*</li>',
+                versions,
+                text,
+                flags=re.I,
+            )
+            with open(fp, r'w', newline='\n', encoding=r'utf-8') as f:
+                f.write(text)
+
+
+def bug_report(args: argparse.Namespace):
+    bug_report_args = [arg for arg in sys.argv[1:] if arg not in (r'--bug-report', r'--worker', r'-v', r'--verbose')]
+    for key in (r'--output-dir', r'--temp-dir', r'--copy-config-to'):
+        pos = -1
+        try:
+            pos = bug_report_args.index(key)
+        except:
+            pass
+        if pos != -1:
+            bug_report_args.pop(pos)
+            bug_report_args.pop(pos)
+
+    if '--git-tags' in bug_report_args:
+        raise Error(r'--git-tags is currently incompatible with --bug-report. This will be fixed in a later version!')
 
-    bug_report_args = [arg for arg in sys.argv[1:] if arg not in BUG_REPORT_STRIP_ARGS]
     bug_report_zip = (Path.cwd() / r'poxy_bug_report.zip').resolve()
 
     print(r'Preparing output paths')
     delete_directory(paths.BUG_REPORT_DIR)
     delete_file(bug_report_zip)
-    os.makedirs(str(paths.BUG_REPORT_DIR), exist_ok=True)
+    paths.BUG_REPORT_DIR.mkdir(exist_ok=True, parents=True)
 
     print(r'Invoking poxy')
     result = subprocess.run(
-        args=[r'poxy', *bug_report_args, r'--bug-report-internal', r'--verbose'],
+        args=[
+            r'poxy',
+            r'--worker',
+            r'--verbose',
+            r'--nocleanup',
+            r'--output-dir',
+            str(paths.BUG_REPORT_DIR),
+            r'--temp-dir',
+            str(paths.BUG_REPORT_DIR / r'temp'),
+            r'--copy-config-to',
+            str(paths.BUG_REPORT_DIR),
+            *bug_report_args,
+        ],
         cwd=str(Path.cwd()),
-        check=False,
-        stdout=subprocess.PIPE,
-        stderr=subprocess.STDOUT,
+        capture_output=True,
         encoding='utf-8',
     )
 
-    if result.stdout is not None:
+    if result.stdout:
         print(r'Writing stdout')
         with open(paths.BUG_REPORT_DIR / r'stdout.txt', r'w', newline='\n', encoding=r'utf-8') as f:
             f.write(result.stdout)
 
-    if result.stderr is not None:
+    if result.stderr:
         print(r'Writing stderr')
         with open(paths.BUG_REPORT_DIR / r'stderr.txt', r'w', newline='\n', encoding=r'utf-8') as f:
             f.write(result.stderr)
@@ -130,8 +404,8 @@ def bug_report():
     delete_directory(paths.BUG_REPORT_DIR)
 
     print(
-        f'Zip generated: {bug_report_zip}\n'
-        'Please attach this file when you make a report at github.com/marzer/poxy/issues, thanks!'
+        f'Zip generated: {Style.BRIGHT}{bug_report_zip}{Style.RESET_ALL}\n'
+        rf'{Fore.CYAN}{Style.BRIGHT}Please attach this file when you make a report at https://github.com/marzer/poxy/issues, thanks!{Style.RESET_ALL}'
     )
 
 
@@ -146,12 +420,13 @@ def main(invoker=True):
     # yapf: disable
     args = argparse.ArgumentParser(
         description=
+        rf'{Fore.CYAN}{Style.BRIGHT}'
         r'''  _ __   _____  ___   _ ''' '\n'
         r''' | '_ \ / _ \ \/ / | | |''' '\n'
         r''' | |_) | (_) >  <| |_| |''' '\n'
         r''' | .__/ \___/_/\_\\__, |''' '\n'
         r''' | |               __/ |''' '\n'
-        r''' |_|              |___/ ''' rf' v{VERSION_STRING} - github.com/marzer/poxy'
+        r''' |_|              |___/ ''' rf'{Style.RESET_ALL} v{VERSION_STRING} - github.com/marzer/poxy'
         '\n\n'
         r'Generate fancy C++ documentation.',
         formatter_class=argparse.RawTextHelpFormatter
@@ -166,8 +441,8 @@ def main(invoker=True):
         r'config',
         type=Path,
         nargs='?',
-        default=Path('.'),
-        help=r'path to poxy.toml or a directory containing it (default: %(default)s)',
+        default=Path.cwd(),
+        help=r'path to poxy.toml or a directory containing it (default: .)',
     )
     args.add_argument(r'-v', r'--verbose', action=r'store_true', help=r"enable very noisy diagnostic output")  #
     make_boolean_optional_arg(args, r'html', default=True, help=r'specify whether HTML output is required')  #
@@ -183,13 +458,13 @@ 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',  #
         choices=[r'light', r'dark', r'custom'],
         default=None,
-        help=r'override the default visual theme (default: read from config)',
+        help=r'sets the default visual theme (default: read from config)',
     )
     args.add_argument(
         r'--threads',
@@ -200,14 +475,27 @@ def main(invoker=True):
     )
     args.add_argument(r'--version', action=r'store_true', help=r"print the version and exit", dest=r'print_version')  #
     make_boolean_optional_arg(args, r'xml', default=False, help=r'specify whether XML output is required')  #
+    make_boolean_optional_arg(
+        args, r'werror', default=None, help=r'treat warnings as errors (default: read from config)'
+    )  #
+    args.add_argument(
+        r'--bug-report', action=r'store_true', help=r"captures all output in a zip file for easier bug reporting."  #
+    )
+    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'werror',
-        default=None,
-        help=r'override the treating of warnings as errors (default: read from config)',  #
+        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'--bug-report', action=r'store_true', help=r"captures all output in a zip file for easier bug reporting."  #
+        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)',
     )
 
     # --------------------------------------------------------------
@@ -222,14 +510,16 @@ def main(invoker=True):
     args.add_argument(r'--update-emoji', action=r'store_true', help=argparse.SUPPRESS)  #
     args.add_argument(r'--update-tests', action=r'store_true', help=argparse.SUPPRESS)  #
     args.add_argument(r'--doxygen-version', action=r'store_true', help=argparse.SUPPRESS)  #
-    args.add_argument(
-        r'--update-mcss', type=Path, default=None, metavar=r'<path>', help=argparse.SUPPRESS, dest=r'mcss'
-    )  #
+    args.add_argument(r'--update-mcss', type=Path, default=None, help=argparse.SUPPRESS)  #
     args.add_argument(  # --xml and --html are the replacements for --xmlonly
         r'--xmlonly', action=r'store_true', help=argparse.SUPPRESS  #
     )
     args.add_argument(r'--xml-v2', action=r'store_true', help=argparse.SUPPRESS)  #
-    args.add_argument(r'--bug-report-internal', action=r'store_true', help=argparse.SUPPRESS)  #
+    args.add_argument(r'--worker', action=r'store_true', help=argparse.SUPPRESS)  #
+    args.add_argument(r'--output-dir', type=Path, default=Path.cwd(), help=argparse.SUPPRESS)  #
+    args.add_argument(r'--temp-dir', type=Path, default=None, help=argparse.SUPPRESS)  #
+    args.add_argument(r'--copy-config-to', type=Path, default=None, help=argparse.SUPPRESS)  #
+    args.add_argument(r'--versions-in-navbar', action=r'store_true', help=argparse.SUPPRESS)  #
     args = args.parse_args()
 
     # --------------------------------------------------------------
@@ -260,11 +550,11 @@ def main(invoker=True):
     # developer-only subcommands
     # --------------------------------------------------------------
 
-    if args.mcss is not None:
+    if args.update_mcss is not None:
         args.update_styles = True
         if args.update_fonts is None:
             args.update_fonts = True
-        mcss.update_bundled_install(args.mcss)
+        mcss.update_bundled_install(args.update_mcss)
     assert_existing_directory(paths.MCSS)
     assert_existing_file(Path(paths.MCSS, r'documentation/doxygen.py'))
 
@@ -286,15 +576,33 @@ def main(invoker=True):
             *[a for a in (r'--verbose' if args.verbose else None, r'--nocleanup' if args.nocleanup else None) if a],
         )
 
-    if args.update_styles or args.update_fonts or args.update_emoji or args.update_tests or args.mcss is not None:
+    if (
+        args.update_styles
+        or args.update_fonts
+        or args.update_emoji
+        or args.update_tests
+        or args.update_mcss is not None
+    ):
         return
 
+    if not args.worker:
+        print(rf'{Fore.CYAN}{Style.BRIGHT}poxy{Style.RESET_ALL} v{VERSION_STRING}')
+
     # --------------------------------------------------------------
     # bug report invocation
     # --------------------------------------------------------------
 
     if args.bug_report:
-        bug_report()
+        bug_report(args)
+        return
+
+    # --------------------------------------------------------------
+    # multi-version invocation
+    # --------------------------------------------------------------
+
+    if args.git_tags:
+        with ScopeTimer(r'All tasks', print_start=False, print_end=True) as timer:
+            multi_version_git_tags(args)
         return
 
     # --------------------------------------------------------------
@@ -305,18 +613,11 @@ def main(invoker=True):
         args.html = False
         args.xml = True
 
-    output_dir = Path.cwd()
-    temp_dir = None
-    if args.bug_report_internal:
-        output_dir = paths.BUG_REPORT_DIR
-        temp_dir = paths.BUG_REPORT_DIR / r'temp'
-        args.nocleanup = True
-
-    with ScopeTimer(r'All tasks', print_start=False, print_end=True) as timer:
+    with ScopeTimer(r'All tasks', print_start=False, print_end=not args.worker) as timer:
         run(
             # named args:
             config_path=args.config,
-            output_dir=output_dir,
+            output_dir=args.output_dir,
             output_html=args.html,
             output_xml=args.xml,
             threads=args.threads,
@@ -328,8 +629,9 @@ def main(invoker=True):
             treat_warnings_as_errors=args.werror,
             theme=args.theme,
             copy_assets=not args.noassets,
-            temp_dir=temp_dir,
-            bug_report=bool(args.bug_report_internal),
+            temp_dir=args.temp_dir,
+            copy_config_to=args.copy_config_to,
+            versions_in_navbar=args.versions_in_navbar,
             # kwargs:
             xml_v2=args.xml_v2,
         )
@@ -355,6 +657,8 @@ def main_blog_post(invoker=True):
         print(VERSION_STRING)
         return
 
+    print(rf'{Fore.CYAN}{Style.BRIGHT}poxy{Style.RESET_ALL} v{VERSION_STRING}')
+
     date = datetime.datetime.now().date()
 
     title = args.title.strip()

poxy/paths.py

@@ -46,3 +46,6 @@ TEMP = Path(tempfile.gettempdir(), r'poxy')
 
 BUG_REPORT_DIR = (TEMP / r'bug_report').resolve()
 """Directory used for assembling bug reports."""
+
+CASE_SENSITIVE = not (Path(str(PACKAGE).upper()).exists() and Path(str(PACKAGE).lower()).exists())
+"""True if the file system is case-sensitive."""

poxy/project.py

@@ -20,6 +20,7 @@ except ImportError:
 
 import datetime
 import itertools
+from colorama import Fore, Style
 
 from . import doxygen, emoji, paths, repos
 from .schemas import *
@@ -1119,7 +1120,7 @@ class Context(object):
         if self.warnings.treat_as_errors:
             raise WarningTreatedAsError(msg)
         else:
-            self.__log(logging.WARNING, rf'Warning: {msg}', indent=indent)
+            self.__log(logging.WARNING, rf'{Style.BRIGHT}{Fore.YELLOW}warning:{Style.RESET_ALL} {msg}', indent=indent)
 
     def verbose_value(self, name, val):
         if not self.__verbose:
@@ -1175,7 +1176,8 @@ class Context(object):
         theme: str,
         copy_assets: bool,
         temp_dir: Path = None,
-        bug_report: bool = False,
+        copy_config_to: Path = None,
+        versions_in_navbar: bool = False,
         **kwargs,
     ):
         self.logger = logger
@@ -1185,9 +1187,7 @@ class Context(object):
         self.cleanup = bool(cleanup)
         self.copy_assets = bool(copy_assets)
         self.verbose_logger = logger if self.__verbose else None
-        self.bug_report = bool(bug_report)
-
-        self.info(rf'Poxy v{VERSION_STRING}')
+        self.versions_in_navbar = bool(versions_in_navbar)
 
         self.verbose_value(r'Context.output_html', self.output_html)
         self.verbose_value(r'Context.output_xml', self.output_xml)
@@ -1242,21 +1242,17 @@ class Context(object):
             self.output_dir = coerce_path(output_dir).resolve()
             self.verbose_value(r'Context.output_dir', self.output_dir)
             assert self.output_dir.is_absolute()
-            self.case_sensitive_paths = not (
-                Path(str(paths.PACKAGE).upper()).exists() and Path(str(paths.PACKAGE).lower()).exists()
-            )
-            self.verbose_value(r'Context.case_sensitive_paths', self.case_sensitive_paths)
 
             # config path
             self.config_path = Path(r'poxy.toml').resolve()
             if config_path is not None:
                 self.config_path = coerce_path(config_path).resolve()
-                if self.config_path.exists() and self.config_path.is_dir():
+                if self.config_path.is_dir():
                     self.config_path = Path(self.config_path, r'poxy.toml')
-                if not self.config_path.exists() or not self.config_path.is_file():
+                if not self.config_path.is_file():
                     raise Error(rf"Config '{self.config_path}' did not exist or was not a file")
-                if self.bug_report:
-                    copy_file(self.config_path, paths.BUG_REPORT_DIR)
+            if copy_config_to is not None and self.config_path.is_file():
+                copy_file(self.config_path, copy_config_to)
             assert self.config_path.is_absolute()
             self.verbose_value(r'Context.config_path', self.config_path)
 
@@ -1270,13 +1266,7 @@ class Context(object):
             if temp_dir is not None:
                 self.temp_dir = Path(temp_dir).absolute()
             else:
-                self.temp_dir = re.sub(r'''[!@#$%^&*()+={}<>;:'"_\\/\n\t -]+''', r'_', str(self.input_dir).strip(r'\/'))
-                if len(self.temp_dir) > 256:
-                    self.temp_dir = str(self.input_dir)
-                    if not self.case_sensitive_paths:
-                        self.temp_dir = self.temp_dir.upper()
-                    self.temp_dir = sha1(self.temp_dir)
-                self.temp_dir = Path(paths.TEMP, self.temp_dir)
+                self.temp_dir = paths.TEMP / 'contexts' / temp_dir_name_for(self.input_dir)
             self.verbose_value(r'Context.temp_dir', self.temp_dir)
             assert self.temp_dir.is_absolute()
 
@@ -1716,6 +1706,12 @@ class Context(object):
                     elif self.navbar[i] in (r'sponsorship', r'funding', r'fund'):
                         self.navbar[i] = r'sponsor'
 
+                # version switcher
+                if self.versions_in_navbar and r'version' not in self.navbar:
+                    self.navbar.append(r'version')
+                while not self.versions_in_navbar and r'version' in self.navbar:
+                    self.navbar.remove(r'version')
+
                 # twitter
                 if self.twitter and r'twitter' not in self.navbar:
                     self.navbar.append(r'twitter')

poxy/run.py

@@ -1289,7 +1289,7 @@ def preprocess_mcss_config(context: Context):
                 if not found:
                     bar[i] = None
             bar = [b for b in bar if b is not None]
-            # handle theme, repo, sponsor, twitter
+            # handle theme, repo, sponsor, twitter, version
             for i in range(len(bar)):
                 bar[i] = bar[i].strip()
                 if bar[i] == r'repo':
@@ -1343,6 +1343,8 @@ def preprocess_mcss_config(context: Context):
                         + rf'class="poxy-icon sponsor">{svg}</a>',
                         [],
                     )
+                elif bar[i] == r'version':
+                    bar[i] = (rf'<span class="poxy-navbar-version-selector">FIXME</span>', [])
                 elif bar[i] in context.compounds:
                     bar[i] = (
                         rf'<a href="{context.compounds[bar[i]]["filename"]}">{context.compounds[bar[i]]["title"]}</a>',
@@ -1684,7 +1686,8 @@ def run(
     theme: str = None,
     copy_assets: bool = True,
     temp_dir: Path = None,
-    bug_report: bool = False,
+    copy_config_to: Path = None,
+    versions_in_navbar: bool = False,
     **kwargs,
 ):
     timer = lambda desc: ScopeTimer(desc, print_start=True, print_end=context.verbose_logger)
@@ -1704,7 +1707,8 @@ def run(
         theme=theme,
         copy_assets=copy_assets,
         temp_dir=temp_dir,
-        bug_report=bug_report,
+        copy_config_to=copy_config_to,
+        versions_in_navbar=versions_in_navbar,
         **kwargs,
     ) as context:
         preprocess_doxyfile(context)

poxy/utils.py

@@ -11,14 +11,14 @@ import io
 import logging
 import re
 import sys
-import typing
-from pathlib import Path
+import typing  # used transitively
+from pathlib import Path  # used transitively
 
 import requests
 from misk import *
 from trieregex import TrieRegEx
 
-from . import paths
+from . import paths  # used transitively
 
 # =======================================================================================================================
 # FUNCTIONS
@@ -115,6 +115,16 @@ def remove_duplicates(vals: list) -> list:
     return new_vals
 
 
+def temp_dir_name_for(input, path=None):
+    out = re.sub(r'''[!@#$%^&*()+={}<>;:'"_\\/\n\t -]+''', r'_', str(input).strip(r'\/'))
+    if len(out) > 256:
+        out = str(input)
+        if not paths.CASE_SENSITIVE:
+            out = out.upper()
+        out = sha1(out)
+    return out
+
+
 # =======================================================================================================================
 # REGEX REPLACER
 # =======================================================================================================================

poxy/version.txt

@@ -1 +1 @@
-0.15.0
+0.17.0

{poxy-0.15.0.dist-info → poxy-0.17.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: poxy
-Version: 0.15.0
+Version: 0.17.0
 Summary: Documentation generator for C++.
 Author-email: Mark Gillard <mark.gillard@outlook.com.au>
 License: MIT
@@ -28,6 +28,7 @@ Requires-Dist: tomli
 Requires-Dist: schema !=0.7.5
 Requires-Dist: requests
 Requires-Dist: trieregex
+Requires-Dist: colorama
 
 # poxy
 
@@ -100,7 +101,8 @@ 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]
+            [--werror | --no-werror] [--bug-report] [--git-tags]
+            [--squash-patches | --no-squash-patches] [--min-version <version>]
             [config]
 
   _ __   _____  ___   _
@@ -108,7 +110,7 @@ usage: poxy [-h] [-v] [--html | --no-html] [--ppinclude <regex>] [--ppexclude <r
  | |_) | (_) >  <| |_| |
  | .__/ \___/_/\_\\__, |
  | |               __/ |
- |_|              |___/  v0.12.0 - github.com/marzer/poxy
+ |_|              |___/  v0.17.0 - github.com/marzer/poxy
 
 Generate fancy C++ documentation.
 
@@ -118,17 +120,24 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   -v, --verbose         enable very noisy diagnostic output
-  --html, --no-html     specify whether HTML output is required (default: True)
+  --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}
-                        override the default visual theme (default: read from config)
+                        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 (default: False)
+  --xml, --no-xml       specify whether XML output is required
   --werror, --no-werror
-                        override the treating of warnings as errors (default: read from config)
+                        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:
@@ -212,6 +221,15 @@ Poxy bundles a fork of m.css, used per the [MIT/Expat license](https://github.co
 
 # 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`
+-   added colour to output
+
 ## v0.15.0 - 2023-12-08
 
 -   added config option `main_page` (a.k.a. `USE_MDFILE_AS_MAINPAGE`)

{poxy-0.15.0.dist-info → poxy-0.17.0.dist-info}/RECORD

@@ -5,30 +5,30 @@ poxy/doxygen.py,sha256=nHygTYfKqh4M0hcdomWK5J3T16GZ7owM5oaWa141Ky4,46372
 poxy/emoji.py,sha256=Vj2ZbUq1MewLMVoLtH2xP_jZToRoNi52AgrIg3VhUuU,3410
 poxy/fixers.py,sha256=aUIQu4YEaygDK4YIaQJ9HsbP6uUKR3XYfroJQeps64M,44783
 poxy/graph.py,sha256=xI7xoV6-yTM-gh2OBARakANLHzGYBwwhwJHchQz2EKw,31959
-poxy/main.py,sha256=Eo38pPB02yHB5u6CbRsl1dfJyPyR2xqoYggGrEqN4Vs,14205
+poxy/main.py,sha256=X8IvjjEnxwV0oT2lv5cP24CQjxHKpsxDmfByoPP2gxg,26937
 poxy/mcss.py,sha256=j9PmkfjcwaKdKBauwiPKhSeKGNmGiBt0i_WcnVAV3Hk,2157
-poxy/paths.py,sha256=nLwBy0a0MA1yXO9JqLsmr1kajuo6PvABqz9rjiwNJXE,1391
-poxy/project.py,sha256=DhSAr-HdI_FPW4jbD9Ud8_XZNcnz-gCOd7T4aFyd-mw,96645
+poxy/paths.py,sha256=OqyP9bIIhW0zyWL6PV2TVV9zsrtvnb25_XNmHlFJmQ8,1540
+poxy/project.py,sha256=TMb3kiMhlvvu4X4XsdtwrhbF2vWOZoeAKu15aMu3bbY,96377
 poxy/repos.py,sha256=rUOVTvR6KxrkSvEA0S340OzMStbSk2SBJUEzKEIynzc,3945
-poxy/run.py,sha256=UT-65Op-tQkIGExKXEXEecwrpZhL1OVcsvVKGezDSdU,76806
+poxy/run.py,sha256=ze2A5YI26KXFrh-t1wGODgIJQRo5lR9-9eQhvhnloZc,77049
 poxy/schemas.py,sha256=57qLWubeIWQUwwTpjRBggPBy70PTQS5JWKzUDKRuBkQ,2490
 poxy/soup.py,sha256=gMXKigNJDuJWWFhPpD5Gu9gbeyVVXo7SrjL1GcsqlMs,7678
 poxy/svg.py,sha256=tsMcKIxQ8OVmXEabqwKDkdEqYV4zI5wM0AJ-E1EXmVo,2657
-poxy/utils.py,sha256=F1Rpb3H7h0GUSuQSljwmgt-V-Nv115VzxTP4MDWH088,5398
+poxy/utils.py,sha256=0_HRU6GxlwJ5TXPJId2j8zQJnUZ8TJBiBU6wqgrMjrI,5748
 poxy/version.py,sha256=N5I7nr5zcmAy-hhgZFi7KfFPV-lB_ueD_Xx6R7XQ-tk,668
-poxy/version.txt,sha256=-EBaczDChwKNRww-41Bvh48a2F7XnB0a3BnfL_c5iRU,7
+poxy/version.txt,sha256=AtOOmOiPSo3C6kDbt2kzhgEGb8lJILUogqFPIa2X9-4,7
 poxy/xml_utils.py,sha256=dJEtHyp4lORHhmBt1E9miRH48PpPM6WRlLEdMhn0Yi8,2183
 poxy/css/m-special.css,sha256=dLVigwqsg_Htm6CESQGemyOKjb-plBlFk54dsAoOd_A,4644
 poxy/css/m-theme-dark.css,sha256=UbAEz9JAgJ1PJJG-Oy9UG2_DUqYTaPJm1cDvVGy5kYk,4186
 poxy/css/m-theme-light.css,sha256=mpXFxB3Uz8_Zklw1cHuJaUA5rxkGvvlOBA2S3Pl1tCY,8035
-poxy/css/poxy-overrides.css,sha256=l8bP4SfEk2DVsKBvIMMZIxLaMLy1M0aR1GjpaE52SYA,10426
+poxy/css/poxy-overrides.css,sha256=3G04c2KR9ZErJo_ivgH1D86XtMP3vPJ4yrLHBvHTrq4,10426
 poxy/css/poxy-pygments.css,sha256=xuyYAQ6agAzb4WnjK2emHvcmuy4gOJejogerO7GBJTw,8376
 poxy/css/poxy-theme-dark.css,sha256=-uBMAbHHFsAdmBbNVcX_7waOcs_uiNVBHCRMeKmAtP4,897
 poxy/css/poxy-theme-light.css,sha256=YB29Y9IBhAZbRRu2RITRRigaRp0RBRg_MsyCV0u8wYo,1363
 poxy/css/poxy.css,sha256=wf_XA8DNMH7pML9d1v2p73AI6rGCjcr4hQxNlfdT-d8,1373
 poxy/generated/6aa12ac32e258617e37a0030dc54f789b894368b.css,sha256=2dgvV-yz0S6U1FUH3mPPfVOy7Zt5-RnG7J1bTlXpyLo,16324
 poxy/generated/emoji.json,sha256=4djkUv00kbpfcXE2ytUk08NxzOg_28tECuDqo8U6bkE,250504
-poxy/generated/poxy.css,sha256=5YyhhQ-jd8PRxIlgS77OtX3x-J6uue8kL_pTiOfa_9g,144548
+poxy/generated/poxy.css,sha256=yGs-703hBQ1WMUwnfpiruvj3sykgz5vXF-wC0PDH624,144548
 poxy/generated/fonts/6xK1dSBYKcSV-LCoeQqfX1RYOo3qPZ7jsDJT9g.woff2,sha256=aKqs2fm9oq7U6gUieWuM5I7fvSrdqeREtzFQtbd4Fmk,1036
 poxy/generated/fonts/6xK1dSBYKcSV-LCoeQqfX1RYOo3qPZ7ksDJT9g.woff2,sha256=E9YKtNAGDp7xjSo4a84V9pBTGC2pz6taS6rEgV8eqTY,1212
 poxy/generated/fonts/6xK1dSBYKcSV-LCoeQqfX1RYOo3qPZ7nsDI.woff2,sha256=UA-Kr2ndz3GhbOrljJJ_AzcbM2ZRheFt80e2f38Rvbk,14160
@@ -176,10 +176,10 @@ poxy/mcss/plugins/m/plots.py,sha256=tiPvTZDkJ-Ab7xSVUhi5CFf_KvO017ZEtxS-ZQYJPiM,
 poxy/mcss/plugins/m/qr.py,sha256=EpYTecbB0m6IzJMDNpIeMjh3-bxisGw6sCdQgL3_Zl4,4183
 poxy/mcss/plugins/m/sphinx.py,sha256=OZHtZ0qVHYHGxJVpSARk_WQiIr6o9B-CTqx2Limfyuw,30965
 poxy/mcss/plugins/m/vk.py,sha256=MiZeFEagOkMBHfNXYf1YEaooCbgoGBtFY9K16CDqdaw,3108
-poxy-0.15.0.dist-info/LICENSE.txt,sha256=kp84JW_RPClTO5Hz6yHQ9jKPfUMerlHHAeyU0VpXV_E,1064
-poxy-0.15.0.dist-info/METADATA,sha256=4ORW3fkvgEIUAJdxJVq_fLYW5ugYnJCqgzbFA2Ug7TI,18887
-poxy-0.15.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-poxy-0.15.0.dist-info/entry_points.txt,sha256=yWiOmptj1Ga_dDEU9ch16hRgmzDE8bgrtDkGbH7VFYc,66
-poxy-0.15.0.dist-info/top_level.txt,sha256=vAxxbZDX_cQ6rfRZ1SYSStSdMMlsHEP-zgzBSB0gPco,5
-poxy-0.15.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-poxy-0.15.0.dist-info/RECORD,,
+poxy-0.17.0.dist-info/LICENSE.txt,sha256=kp84JW_RPClTO5Hz6yHQ9jKPfUMerlHHAeyU0VpXV_E,1064
+poxy-0.17.0.dist-info/METADATA,sha256=DrK1i-r3OyMIsuuS1rCXA40UxijYv0MV466O0IBf5wA,19700
+poxy-0.17.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+poxy-0.17.0.dist-info/entry_points.txt,sha256=yWiOmptj1Ga_dDEU9ch16hRgmzDE8bgrtDkGbH7VFYc,66
+poxy-0.17.0.dist-info/top_level.txt,sha256=vAxxbZDX_cQ6rfRZ1SYSStSdMMlsHEP-zgzBSB0gPco,5
+poxy-0.17.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+poxy-0.17.0.dist-info/RECORD,,

{poxy-0.15.0.dist-info → poxy-0.17.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: bdist_wheel (0.43.0)
 Root-Is-Purelib: true
 Tag: py3-none-any