From 305fca05a225596f381184455834c5e19d407d50 Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Wed, 11 Nov 2026 09:01:07 -0800 Subject: [PATCH] docs: pin the reference install line to the page's major Each generated reference page now installs the major it describes, so a reader of the 7.x page doesn't get 8.0 after it ships. Co-Authored-By: Claude Opus 5.5 --- bin/docs_scripts/generate_markdown.py | 12 +++++++++++- docs/getting-started.md | 2 +- posthog/test/test_reference_markdown.py | 7 +++++++ references/posthog-python-7.md | 2 +- references/posthog-python-8.md | 2 +- references/posthog-python-reference.md | 2 +- 6 files changed, 22 insertions(+), 5 deletions(-) diff --git a/bin/docs_scripts/generate_markdown.py b/bin/docs_scripts/generate_markdown.py index 8ade17f58..dd71b9c46 100644 --- a/bin/docs_scripts/generate_markdown.py +++ b/bin/docs_scripts/generate_markdown.py @@ -214,6 +214,16 @@ def nest(markdown: str) -> str: return "\n".join(out) +def getting_started(major: int) -> str: + """docs/getting-started.md for one major. Its install line pins that major, so a + reader never installs a major the page doesn't describe.""" + text = (ROOT / "docs/getting-started.md").read_text() + if "{major}" not in text: + raise SystemExit("docs/getting-started.md: the install line must pin {major}") + pinned = text.replace("{major}", str(major)) + return nest(pinned.replace("{next_major}", str(major + 1))) + + def write(name: str, sections: list[str]) -> None: (ROOT / "references" / name).write_text("\n\n".join(sections) + "\n") print(f"wrote references/{name}") @@ -239,7 +249,7 @@ def main() -> None: (ROOT / "posthog/version.py").read_text().split('"')[1].split(".")[0] ) major = opts.major or declared - started = nest((ROOT / "docs/getting-started.md").read_text()) + started = getting_started(major) body = [ "## Getting started", started, diff --git a/docs/getting-started.md b/docs/getting-started.md index 27d91f176..3f7f72de7 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -7,7 +7,7 @@ To send your first event, install the package, create a client, capture an event ## Install ```bash -pip install posthog +pip install "posthog>={major},<{next_major}" ``` ## Initialize diff --git a/posthog/test/test_reference_markdown.py b/posthog/test/test_reference_markdown.py index bba347504..0c21a7818 100644 --- a/posthog/test/test_reference_markdown.py +++ b/posthog/test/test_reference_markdown.py @@ -65,3 +65,10 @@ def test_summaries_keep_the_whole_first_paragraph(pkg): generator.clean(cls) md = generator.entry(cls, "FeatureFlagEvaluations") assert "on the first access per (distinct_id, flag, value) tuple" in md + + +@pytest.mark.parametrize("major, pin", [(7, '"posthog>=7,<8"'), (8, '"posthog>=8,<9"')]) +def test_getting_started_pins_the_install_to_the_page_major(major, pin): + text = generator.getting_started(major) + assert f"pip install {pin}" in text + assert "{major}" not in text and "{next_major}" not in text diff --git a/references/posthog-python-7.md b/references/posthog-python-7.md index bfa813789..e8b38ed62 100644 --- a/references/posthog-python-7.md +++ b/references/posthog-python-7.md @@ -89,7 +89,7 @@ To send your first event, install the package, create a client, capture an event ### Install ```bash -pip install posthog +pip install "posthog>=7,<8" ``` ### Initialize diff --git a/references/posthog-python-8.md b/references/posthog-python-8.md index 8f9198f3a..f89ad3bfb 100644 --- a/references/posthog-python-8.md +++ b/references/posthog-python-8.md @@ -89,7 +89,7 @@ To send your first event, install the package, create a client, capture an event ### Install ```bash -pip install posthog +pip install "posthog>=8,<9" ``` ### Initialize diff --git a/references/posthog-python-reference.md b/references/posthog-python-reference.md index fa798a96c..d48de7843 100644 --- a/references/posthog-python-reference.md +++ b/references/posthog-python-reference.md @@ -89,7 +89,7 @@ To send your first event, install the package, create a client, capture an event ### Install ```bash -pip install posthog +pip install "posthog>=7,<8" ``` ### Initialize