feat: support symlinked docs for local dev

Makefile

@@ -1,9 +1,14 @@
+ifdef POETRY_REPO
+WEBSITE_ARGS = --local="$(POETRY_REPO)" --editable
+endif
+
 .PHONY: help
 help: ## Show this help
 	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z -]+:.*?## / {printf "\033[36m%-10s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort
 
 .PHONY: clean
 clean: ## Clean generated files
+	@unlink content/docs &>/dev/null || true
 	@rm -rf assets/ content/docs/ public/ resources/
 
 .PHONY: site
@@ -17,5 +22,5 @@ node_modules: package.json package-lock.json
 
 content/docs: pyproject.toml
 	poetry install
-	poetry run ./bin/website configure
-	poetry run ./bin/website docs pull
+	poetry run ./bin/website configure $(WEBSITE_ARGS)
+	poetry run ./bin/website docs pull $(WEBSITE_ARGS)

README.md

@@ -7,16 +7,25 @@ It's built using the static site generator [Hugo](https://gohugo.io) and the Mar
 ## Requirements
 
 - [Poetry](https://python-poetry.org/docs/master/#installing-with-the-official-installer)
-- [Node.js 14](https://nodejs.org/en/download/) (and `npm`)
+- [Node.js 16](https://nodejs.org/en/download/) (and `npm`)
 
 ## Local development
 
-If you want to work on this project locally, follow the instructions below:
+To work on this project locally, first fork and clone this repo. Then:
 
-1. Fork this repository
-1. Clone your fork locally
-1. Run `make site`, which will:
-   - Fetch `docs/*.md` from `poetry` repo into `content/docs`
-   - Concurrently run `rollup` to compile assets and `hugo` to serve content
+```sh
+make site
+```
+
+or, to instead use docs from a local `poetry` repo:
+
+```sh
+make site POETRY_REPO=../path/to/local/poetry/repo
+```
+
+This will
+
+- Either fetch or symlink `docs/*.md` from the `poetry` repo into `content/docs`
+- Concurrently run `rollup` to compile assets and `hugo` to serve content
 
 The website will now be accessible at <http://localhost:1313> and reload on any changes.

bin/website

@@ -51,7 +51,10 @@ def get_branches() -> list[str]:
 class ConfigureCommand(Command):
     name = "configure"
     description = "Generate website config.toml file."
-    options = [option("local", None, "Build from local Poetry source.", flag=False)]
+    options = [
+        option("local", None, "Build from local Poetry source.", flag=False),
+        option("editable", None, "Symlink local Poetry source rather than copying."),
+    ]
 
     @staticmethod
     def get_configuration(file: Path | None = None) -> dict[str, Any]:
@@ -105,13 +108,19 @@ class DocsPullCommand(ConfigureCommand):
         branches = get_branches()
         default_version = content["config"]["params"]["documentation"]["defaultVersion"]
 
-        if self.DESTINATION.exists():
+        if self.DESTINATION.is_symlink():
+            self.DESTINATION.unlink()
+        elif self.DESTINATION.exists():
             shutil.rmtree(self.DESTINATION)
 
         self.DESTINATION.mkdir(parents=True)
 
         if self.option("local"):
-            self._pull_local_version(Path(self.option("local")), self.DESTINATION)
+            self._pull_local_version(
+                src=Path(self.option("local")),
+                dest=self.DESTINATION,
+                editable=self.option("editable"),
+            )
             return 0
 
         for name, version in versions.items():
@@ -127,10 +136,16 @@ class DocsPullCommand(ConfigureCommand):
         return 0
 
     @staticmethod
-    def _pull_local_version(src: Path, dest: Path) -> None:
-        # Copy files at the root of the destination
-        for filepath in Path(src).joinpath("docs").glob("*.md"):
-            shutil.copyfile(filepath, dest.joinpath(filepath.name))
+    def _pull_local_version(src: Path, dest: Path, editable: bool = False) -> None:
+        src = Path(src).joinpath("docs")
+        if editable:
+            # Symlink directory to destination
+            dest.rmdir()
+            dest.symlink_to(src.resolve(), target_is_directory=True)
+        else:
+            # Copy files at the root of the destination
+            for filepath in src.glob("*.md"):
+                shutil.copyfile(filepath, dest.joinpath(filepath.name))
 
     def _pull_version(
         self,