From 1c7874450abf022bd83f87adec318036c2300db6 Mon Sep 17 00:00:00 2001 From: Andre Lorbach Date: Mon, 4 May 2026 14:47:41 +0200 Subject: [PATCH 1/3] docs: drop legacy-html from handbook URLs Imported manuals live under user-guide/chapters/; overview moves to user-guide/overview.md (was legacy-html-manuals.md). prepare_docs.py, mkdocs nav, and cross-links updated. Gitignore chapters/ build output. --- .gitignore | 2 +- doc-site/docs/index.md | 2 +- doc-site/docs/user-guide/interface-map.md | 6 +-- .../overview.md} | 20 ++++---- doc-site/docs/user-guide/quick-start.md | 4 +- doc-site/mkdocs.yml | 22 ++++---- doc-site/prepare_docs.py | 50 ++++++++++++------- 7 files changed, 59 insertions(+), 47 deletions(-) rename doc-site/docs/{legacy-html-manuals.md => user-guide/overview.md} (56%) diff --git a/.gitignore b/.gitignore index f6ba599..3e2c1db 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,6 @@ src/config.php /e2e/playwright-report/ /e2e/test-results/ /doc-site/_site/ -/doc-site/docs/legacy-html/ +/doc-site/docs/user-guide/chapters/ src/index.html diff --git a/doc-site/docs/index.md b/doc-site/docs/index.md index fc6d359..aeeb128 100644 --- a/doc-site/docs/index.md +++ b/doc-site/docs/index.md @@ -6,6 +6,6 @@ LogAnalyzer is a PHP web front end for browsing syslog and related log data. Thi - **[Quick start](user-guide/quick-start.md)** — run with Docker and skim the UI with screenshots. - **[Interface map](user-guide/interface-map.md)** — main routes and where to read more. - [Third-party and bundled libraries](third-party.md) lists versions and update notes. -- [User guide overview](legacy-html-manuals.md) indexes every imported manual page; sources remain [`doc/*.html`](https://github.com/rsyslog/loganalyzer/tree/master/doc) on GitHub. +- [User guide overview](user-guide/overview.md) indexes every imported manual page; sources remain [`doc/*.html`](https://github.com/rsyslog/loganalyzer/tree/master/doc) on GitHub. Handbook build: `doc-site/`; published at [https://rsyslog.github.io/loganalyzer/](https://rsyslog.github.io/loganalyzer/) (`site_url` in `mkdocs.yml`). diff --git a/doc-site/docs/user-guide/interface-map.md b/doc-site/docs/user-guide/interface-map.md index bd9b6b8..2d4c5e5 100644 --- a/doc-site/docs/user-guide/interface-map.md +++ b/doc-site/docs/user-guide/interface-map.md @@ -11,12 +11,12 @@ LogAnalyzer is a PHP web UI. URLs below are the primary entry points; your deplo | Reports | `reports.php` | Report-oriented views. | | Administration | `admin/index.php` | Manage sources, users, and system options (administrators). | -See [Search syntax](../legacy-html/searching.md) for query syntax used in filters and searches. +See [Search syntax](chapters/searching.md) for query syntax used in filters and searches. ## Documentation trail -- **Operational setup:** [Docker & CI](../docker.md), [Installation](../legacy-html/install.md), [Troubleshooting](../legacy-html/troubleshoot.md). -- **Using the product:** [Basics](../legacy-html/basics.md), [Search syntax](../legacy-html/searching.md), [Text log files](../legacy-html/textfiles.md), [Windows Event Log](../legacy-html/windowsevent.md). +- **Operational setup:** [Docker & CI](../docker.md), [Installation](chapters/install.md), [Troubleshooting](chapters/troubleshoot.md). +- **Using the product:** [Basics](chapters/basics.md), [Search syntax](chapters/searching.md), [Text log files](chapters/textfiles.md), [Windows Event Log](chapters/windowsevent.md). ## Screenshots diff --git a/doc-site/docs/legacy-html-manuals.md b/doc-site/docs/user-guide/overview.md similarity index 56% rename from doc-site/docs/legacy-html-manuals.md rename to doc-site/docs/user-guide/overview.md index 15ef146..d7d75c5 100644 --- a/doc-site/docs/legacy-html-manuals.md +++ b/doc-site/docs/user-guide/overview.md @@ -6,16 +6,16 @@ Every `*.html` manual under [`doc/`](https://github.com/rsyslog/loganalyzer/blob ## Pages (in-site) -- [Documentation home](legacy-html/manual.md) (`manual.html`) -- [Basics](legacy-html/basics.md) (`basics.html`) -- [Installation](legacy-html/install.md) (`install.html`) -- [Search syntax](legacy-html/searching.md) (`searching.html`) -- [Troubleshooting](legacy-html/troubleshoot.md) (`troubleshoot.html`) -- [Build from repo](legacy-html/build_from_repo.md) (`build_from_repo.html`) -- [Free support](legacy-html/free_support.md) (`free_support.html`) -- [Professional services](legacy-html/professional_services.md) (`professional_services.html`) -- [Text log files](legacy-html/textfiles.md) (`textfiles.html`) -- [Windows Event Log](legacy-html/windowsevent.md) (`windowsevent.html`) +- [Documentation home](chapters/manual.md) (`manual.html`) +- [Basics](chapters/basics.md) (`basics.html`) +- [Installation](chapters/install.md) (`install.html`) +- [Search syntax](chapters/searching.md) (`searching.html`) +- [Troubleshooting](chapters/troubleshoot.md) (`troubleshoot.html`) +- [Build from repo](chapters/build_from_repo.md) (`build_from_repo.html`) +- [Free support](chapters/free_support.md) (`free_support.html`) +- [Professional services](chapters/professional_services.md) (`professional_services.html`) +- [Text log files](chapters/textfiles.md) (`textfiles.html`) +- [Windows Event Log](chapters/windowsevent.md) (`windowsevent.html`) ## Source in the repository diff --git a/doc-site/docs/user-guide/quick-start.md b/doc-site/docs/user-guide/quick-start.md index 5bb71e0..23d5f40 100644 --- a/doc-site/docs/user-guide/quick-start.md +++ b/doc-site/docs/user-guide/quick-start.md @@ -39,5 +39,5 @@ PNG files under `doc-site/docs/assets/user-guide/` are produced with **Playwrigh ## Go deeper - [Interface map](interface-map.md) — how main areas fit together. -- [User guide overview](../legacy-html-manuals.md) — full list of imported chapters from `doc/`. -- [Installation](../legacy-html/install.md) and [Basics](../legacy-html/basics.md) for configuration and concepts. +- [User guide overview](overview.md) — full list of imported chapters from `doc/`. +- [Installation](chapters/install.md) and [Basics](chapters/basics.md) for configuration and concepts. diff --git a/doc-site/mkdocs.yml b/doc-site/mkdocs.yml index b5c9fe9..e9cb024 100644 --- a/doc-site/mkdocs.yml +++ b/doc-site/mkdocs.yml @@ -30,18 +30,18 @@ nav: - Home: index.md - Docker & CI (from AGENTS.md): docker.md - LogAnalyzer user guide: - - Overview: legacy-html-manuals.md + - Overview: user-guide/overview.md - Quick start: user-guide/quick-start.md - Interface map: user-guide/interface-map.md - - Documentation home: legacy-html/manual.md - - Basics: legacy-html/basics.md - - Installation: legacy-html/install.md - - Search syntax: legacy-html/searching.md - - Troubleshooting: legacy-html/troubleshoot.md - - Build from repo: legacy-html/build_from_repo.md - - Free support: legacy-html/free_support.md - - Professional services: legacy-html/professional_services.md - - Text log files: legacy-html/textfiles.md - - Windows Event Log: legacy-html/windowsevent.md + - Documentation home: user-guide/chapters/manual.md + - Basics: user-guide/chapters/basics.md + - Installation: user-guide/chapters/install.md + - Search syntax: user-guide/chapters/searching.md + - Troubleshooting: user-guide/chapters/troubleshoot.md + - Build from repo: user-guide/chapters/build_from_repo.md + - Free support: user-guide/chapters/free_support.md + - Professional services: user-guide/chapters/professional_services.md + - Text log files: user-guide/chapters/textfiles.md + - Windows Event Log: user-guide/chapters/windowsevent.md - Repository README: project-readme.md - Third-party components: third-party.md diff --git a/doc-site/prepare_docs.py b/doc-site/prepare_docs.py index a7f7eee..73abadc 100644 --- a/doc-site/prepare_docs.py +++ b/doc-site/prepare_docs.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Prepare doc-site/docs from repository Markdown; embed legacy HTML as MkDocs pages.""" +"""Prepare doc-site/docs from repository Markdown; embed upstream doc/*.html as MkDocs pages under user-guide/chapters/.""" from __future__ import annotations import os @@ -9,7 +9,10 @@ REPO_ROOT = Path(__file__).resolve().parent.parent OUT_DIR = Path(__file__).resolve().parent / "docs" -LEGACY_SUBDIR = "legacy-html" +# Handbook-native pages live in user-guide/; imported doc/*.html render under user-guide/chapters/. +USER_GUIDE_DIR = "user-guide" +IMPORTED_CHAPTERS_DIR = "chapters" +OVERVIEW_MD = "overview.md" REPO_URL = os.environ.get("GHP_REPO_URL", "https://github.com/rsyslog/loganalyzer").rstrip("/") DEFAULT_BRANCH = os.environ.get("GHP_DEFAULT_BRANCH", "master").strip() or "master" @@ -122,13 +125,15 @@ def _ordered_legacy_stems(stems: set[str]) -> list[str]: def _format_legacy_nav_lines(stems_ordered: list[str]) -> list[str]: lines = [ LEGACY_NAV_HEADER, - " - Overview: legacy-html-manuals.md", - " - Quick start: user-guide/quick-start.md", - " - Interface map: user-guide/interface-map.md", + f" - Overview: {USER_GUIDE_DIR}/{OVERVIEW_MD}", + f" - Quick start: {USER_GUIDE_DIR}/quick-start.md", + f" - Interface map: {USER_GUIDE_DIR}/interface-map.md", ] for stem in stems_ordered: label = LEGACY_NAV_LABELS.get(stem, stem.replace("_", " ").title()) - lines.append(f" - {label}: legacy-html/{stem}.md") + lines.append( + f" - {label}: {USER_GUIDE_DIR}/{IMPORTED_CHAPTERS_DIR}/{stem}.md" + ) return lines @@ -190,10 +195,20 @@ def main() -> int: print(f"Wrote {OUT_DIR / 'project-readme.md'}") manuals = REPO_ROOT / "doc" if manuals.is_dir(): - legacy_out = OUT_DIR / LEGACY_SUBDIR - if legacy_out.is_dir(): - shutil.rmtree(legacy_out) - legacy_out.mkdir(parents=True, exist_ok=True) + guide_root = OUT_DIR / USER_GUIDE_DIR + guide_root.mkdir(parents=True, exist_ok=True) + chapters_out = guide_root / IMPORTED_CHAPTERS_DIR + if chapters_out.is_dir(): + shutil.rmtree(chapters_out) + chapters_out.mkdir(parents=True, exist_ok=True) + # Remove pre-URL-cleanup output locations (generated or leftover). + legacy_old = OUT_DIR / "legacy-html" + if legacy_old.is_dir(): + shutil.rmtree(legacy_old) + old_hub = OUT_DIR / "legacy-html-manuals.md" + if old_hub.is_file(): + old_hub.unlink() + html_files = sorted(manuals.glob("*.html")) stems = {f.stem for f in html_files} @@ -202,11 +217,11 @@ def main() -> int: doc_title, body = _extract_title_and_body(raw) body = _rewrite_hrefs(body, stems) md_name = src.with_suffix(".md").name - _write_legacy_markdown(legacy_out / md_name, doc_title, body) - print(f"Wrote {legacy_out / md_name} <- {src.name}") + _write_legacy_markdown(chapters_out / md_name, doc_title, body) + print(f"Wrote {chapters_out / md_name} <- {src.name}") blob_base = f"{REPO_URL}/blob/{DEFAULT_BRANCH}/doc" - rel_prefix = f"{LEGACY_SUBDIR}/" + rel_prefix = f"{IMPORTED_CHAPTERS_DIR}/" ordered = _ordered_legacy_stems(stems) stem_to_html = {f.stem: f.name for f in html_files} @@ -240,12 +255,9 @@ def main() -> int: "", ] ) - (OUT_DIR / "legacy-html-manuals.md").write_text( - "\n".join(lines) + "\n", - encoding="utf-8", - newline="\n", - ) - print(f"Wrote {OUT_DIR / 'legacy-html-manuals.md'}") + overview_path = OUT_DIR / USER_GUIDE_DIR / OVERVIEW_MD + overview_path.write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n") + print(f"Wrote {overview_path}") _patch_mkdocs_legacy_nav(_ordered_legacy_stems(stems)) return 0 From 73d37d913e7672482f6ce3de88f47c186f58002b Mon Sep 17 00:00:00 2001 From: Andre Lorbach Date: Mon, 4 May 2026 15:01:20 +0200 Subject: [PATCH 2/3] docs: run legacy handbook path cleanup even when doc/ is missing Address PR #120 review: removing legacy-html/ and legacy-html-manuals.md should not depend on doc/*.html being present so partial checkouts or missing doc/ still drop stale output. Co-authored-by: Cursor --- doc-site/prepare_docs.py | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/doc-site/prepare_docs.py b/doc-site/prepare_docs.py index 73abadc..1387a2e 100644 --- a/doc-site/prepare_docs.py +++ b/doc-site/prepare_docs.py @@ -182,6 +182,16 @@ def _write_legacy_markdown( out_path.write_text(md, encoding="utf-8", newline="\n") +def _remove_pre_migration_doc_artifacts(out_dir: Path) -> None: + """Remove handbook output from the pre-PR layout (legacy-html/, legacy-html-manuals.md).""" + legacy_old = out_dir / "legacy-html" + if legacy_old.is_dir(): + shutil.rmtree(legacy_old) + old_hub = out_dir / "legacy-html-manuals.md" + if old_hub.is_file(): + old_hub.unlink() + + def main() -> int: OUT_DIR.mkdir(parents=True, exist_ok=True) agents = REPO_ROOT / "AGENTS.md" @@ -193,6 +203,7 @@ def main() -> int: text = readme.read_text(encoding="utf-8", errors="replace") (OUT_DIR / "project-readme.md").write_text(text, encoding="utf-8", newline="\n") print(f"Wrote {OUT_DIR / 'project-readme.md'}") + _remove_pre_migration_doc_artifacts(OUT_DIR) manuals = REPO_ROOT / "doc" if manuals.is_dir(): guide_root = OUT_DIR / USER_GUIDE_DIR @@ -201,13 +212,6 @@ def main() -> int: if chapters_out.is_dir(): shutil.rmtree(chapters_out) chapters_out.mkdir(parents=True, exist_ok=True) - # Remove pre-URL-cleanup output locations (generated or leftover). - legacy_old = OUT_DIR / "legacy-html" - if legacy_old.is_dir(): - shutil.rmtree(legacy_old) - old_hub = OUT_DIR / "legacy-html-manuals.md" - if old_hub.is_file(): - old_hub.unlink() html_files = sorted(manuals.glob("*.html")) stems = {f.stem for f in html_files} From 2eec76c7f35c8d0d41a6c4c836faac147cf20d95 Mon Sep 17 00:00:00 2001 From: Andre Lorbach Date: Mon, 4 May 2026 15:06:05 +0200 Subject: [PATCH 3/3] docs: quote handbook nav labels and harden legacy path cleanup Respond to PR #120 review: YAML keys for user guide nav use _yaml_single_quoted labels; pre-migration artifacts removed via a small loop that handles dir-or-file per path (Gemini code assist). Co-authored-by: Cursor --- doc-site/mkdocs.yml | 26 +++++++++++++------------- doc-site/prepare_docs.py | 20 ++++++++++---------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/doc-site/mkdocs.yml b/doc-site/mkdocs.yml index e9cb024..b550f77 100644 --- a/doc-site/mkdocs.yml +++ b/doc-site/mkdocs.yml @@ -30,18 +30,18 @@ nav: - Home: index.md - Docker & CI (from AGENTS.md): docker.md - LogAnalyzer user guide: - - Overview: user-guide/overview.md - - Quick start: user-guide/quick-start.md - - Interface map: user-guide/interface-map.md - - Documentation home: user-guide/chapters/manual.md - - Basics: user-guide/chapters/basics.md - - Installation: user-guide/chapters/install.md - - Search syntax: user-guide/chapters/searching.md - - Troubleshooting: user-guide/chapters/troubleshoot.md - - Build from repo: user-guide/chapters/build_from_repo.md - - Free support: user-guide/chapters/free_support.md - - Professional services: user-guide/chapters/professional_services.md - - Text log files: user-guide/chapters/textfiles.md - - Windows Event Log: user-guide/chapters/windowsevent.md + - 'Overview': user-guide/overview.md + - 'Quick start': user-guide/quick-start.md + - 'Interface map': user-guide/interface-map.md + - 'Documentation home': user-guide/chapters/manual.md + - 'Basics': user-guide/chapters/basics.md + - 'Installation': user-guide/chapters/install.md + - 'Search syntax': user-guide/chapters/searching.md + - 'Troubleshooting': user-guide/chapters/troubleshoot.md + - 'Build from repo': user-guide/chapters/build_from_repo.md + - 'Free support': user-guide/chapters/free_support.md + - 'Professional services': user-guide/chapters/professional_services.md + - 'Text log files': user-guide/chapters/textfiles.md + - 'Windows Event Log': user-guide/chapters/windowsevent.md - Repository README: project-readme.md - Third-party components: third-party.md diff --git a/doc-site/prepare_docs.py b/doc-site/prepare_docs.py index 1387a2e..3e42e8a 100644 --- a/doc-site/prepare_docs.py +++ b/doc-site/prepare_docs.py @@ -125,14 +125,14 @@ def _ordered_legacy_stems(stems: set[str]) -> list[str]: def _format_legacy_nav_lines(stems_ordered: list[str]) -> list[str]: lines = [ LEGACY_NAV_HEADER, - f" - Overview: {USER_GUIDE_DIR}/{OVERVIEW_MD}", - f" - Quick start: {USER_GUIDE_DIR}/quick-start.md", - f" - Interface map: {USER_GUIDE_DIR}/interface-map.md", + f" - {_yaml_single_quoted('Overview')}: {USER_GUIDE_DIR}/{OVERVIEW_MD}", + f" - {_yaml_single_quoted('Quick start')}: {USER_GUIDE_DIR}/quick-start.md", + f" - {_yaml_single_quoted('Interface map')}: {USER_GUIDE_DIR}/interface-map.md", ] for stem in stems_ordered: label = LEGACY_NAV_LABELS.get(stem, stem.replace("_", " ").title()) lines.append( - f" - {label}: {USER_GUIDE_DIR}/{IMPORTED_CHAPTERS_DIR}/{stem}.md" + f" - {_yaml_single_quoted(label)}: {USER_GUIDE_DIR}/{IMPORTED_CHAPTERS_DIR}/{stem}.md" ) return lines @@ -184,12 +184,12 @@ def _write_legacy_markdown( def _remove_pre_migration_doc_artifacts(out_dir: Path) -> None: """Remove handbook output from the pre-PR layout (legacy-html/, legacy-html-manuals.md).""" - legacy_old = out_dir / "legacy-html" - if legacy_old.is_dir(): - shutil.rmtree(legacy_old) - old_hub = out_dir / "legacy-html-manuals.md" - if old_hub.is_file(): - old_hub.unlink() + for name in ("legacy-html", "legacy-html-manuals.md"): + path = out_dir / name + if path.is_dir(): + shutil.rmtree(path) + elif path.is_file(): + path.unlink() def main() -> int: