auto-generate history from the changelog of the main branch of the poetry repo (#221)

Author: radoering

.gitignore

@@ -2,6 +2,7 @@ node_modules
 public
 assets/assets
 /content/docs
+/content/history.md
 /resources
 .python-version
 .vscode

Makefile

@@ -9,18 +9,18 @@ help: ## Show this help
 .PHONY: clean
 clean: ## Clean generated files
 	@unlink content/docs &>/dev/null || true
-	@rm -rf assets/ content/docs/ public/ resources/
+	@rm -rf assets/ content/docs/ content/history.md public/ resources/
 
 .PHONY: site
-site: node_modules content/docs ## Build and serve site
+site: node_modules content/docs content/history.md ## Build and serve site
 	@test -f assets/assets/app.js || npx rollup --config
 	@npm run dev
 
 node_modules: package.json package-lock.json
 	npm install
 	@touch node_modules
 
-content/docs: pyproject.toml
+content/docs content/history.md &: pyproject.toml
 	poetry install
 	poetry run ./bin/website configure $(WEBSITE_ARGS)
 	poetry run ./bin/website docs pull $(WEBSITE_ARGS)

README.md

@@ -15,6 +15,12 @@ It's built using the static site generator [Hugo](https://gohugo.io) and the Mar
 
 ## Local development
 
+> [!NOTE]
+> The following commands require GNU Make 4.3 or newer (the `Makefile` uses
+> [grouped targets](https://www.gnu.org/software/make/manual/html_node/Multiple-Targets.html),
+> introduced in 4.3). If you are on macOS, which may still ship an older version;
+> install a newer version with `brew install make` and invoke it as `gmake`.
+
 To work on this project locally, first fork and clone this repo. Then:
 
 ```sh

bin/website

@@ -99,7 +99,9 @@ class ConfigureCommand(Command):
 
 
 class DocsPullCommand(ConfigureCommand):
-    DESTINATION: Path = Path(__file__).parent.parent.joinpath("content/docs")
+    DESTINATION = Path(__file__).parent.parent / "content" / "docs"
+    HISTORY_DESTINATION = Path(__file__).parent.parent / "content" / "history.md"
+    HISTORY_FRONTMATTER = "---\ntype: page\nlayout: single\ntitle: History\n---\n\n"
     REPOSITORY = "https://github.com/python-poetry/poetry.git"
 
     name = "docs pull"
@@ -120,12 +122,17 @@ class DocsPullCommand(ConfigureCommand):
 
         self.DESTINATION.mkdir(parents=True)
 
+        if self.HISTORY_DESTINATION.exists():
+            self.HISTORY_DESTINATION.unlink()
+
         if self.option("local"):
+            local_src = Path(self.option("local"))
             self._pull_local_version(
-                src=Path(self.option("local")),
+                src=local_src,
                 dest=self.DESTINATION,
                 editable=self.option("editable"),
             )
+            self._write_history(local_src / "CHANGELOG.md")
             return 0
 
         for name, version in versions.items():
@@ -210,9 +217,24 @@ class DocsPullCommand(ConfigureCommand):
 
                         with path.joinpath(filepath.name).open("w") as f:
                             f.write(new_content)
+
+                if version == "main":
+                    self._write_history(tmp_dir / "CHANGELOG.md")
         finally:
             os.chdir(cwd.as_posix())
 
+    def _write_history(self, changelog: Path) -> None:
+        if not changelog.exists():
+            raise RuntimeError(f"Changelog file not found at {changelog}")
+        self.line(f"  Writing history from <b>{changelog.name}</b>")
+        lines = changelog.read_text(encoding="utf-8").splitlines(keepends=True)
+        # replace changelog heading with history page title
+        if lines and lines[0].lstrip().startswith("# "):
+            lines = lines[1:]
+        while lines and lines[0].strip() == "":
+            lines = lines[1:]
+        self.HISTORY_DESTINATION.write_text(self.HISTORY_FRONTMATTER + "".join(lines))
+
 
 class BuildCommand(DocsPullCommand):
     name = "build"