Better sitemap strategy

.github/workflows/build_docs.yml

@@ -79,7 +79,7 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: docgen-build
-          path: dist/
+          path: dist
 
       - name: Copy build to Pages
         run: |
@@ -91,52 +91,8 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: github-pages-tmp
-          path: _site/
+          path: _site
   
-  publish-pypi:
-    runs-on: ubuntu-latest
-    needs: build
-    if: needs.build.outputs.release == 'true'
-
-    environment:
-      name: pypi
-      url: https://pypi.org/p/${{ env.PYPI_PACKAGE }}
-    permissions:
-      id-token: write
-
-    steps:
-      - name: Download docgen artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: docgen-build
-          path: dist
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-
-  publish-testpypi:
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.event_name == 'workflow_dispatch' && inputs.publish == 'TestPyPI'
-
-    environment:
-      name: testpypi
-      url: https://test.pypi.org/p/${{ env.PYPI_PACKAGE }}
-    permissions:
-      id-token: write
-
-    steps:
-      - name: Download docgen artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: docgen-build
-          path: dist
-
-      - name: Publish to TestPyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          repository-url: https://test.pypi.org/legacy/
-
   generate:
     runs-on: ubuntu-latest
     needs: build
@@ -161,7 +117,7 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: github-pages-tmp
-          path: _site/
+          path: _site
 
   bundle-pages:
     runs-on: ubuntu-latest
@@ -179,28 +135,22 @@ jobs:
         continue-on-error: true
         with:
           ref: gh-pages
-          path: gh-pages/
+          path: _site/dst
 
       - name: Download temporary Pages artifact
         uses: actions/download-artifact@v3
         with:
           name: github-pages-tmp
-          path: _new_site/
+          path: _site/src/docs
       
       - name: Add new docs to site
-        run: hexdoc_merge --source _new_site --dest gh-pages/docs --release "${{ needs.build.outputs.release == true }}"
-
-      - name: Fix permissions
-        run: |
-          chmod -c -R +rX "_site/" | while read line; do
-            echo "::warning title=Invalid file permissions automatically fixed::$line"
-          done
+        run: hexdoc_merge --src _site/src/docs --dst _site/dst/docs --release "${{ needs.build.outputs.release == true }}"
 
       - name: Upload Pages artifact
         uses: actions/upload-artifact@v3
         with:
           name: github-pages
-          path: gh-pages/docs
+          path: _site/dst/docs
 
   deploy-pages:
     runs-on: ubuntu-latest
@@ -211,14 +161,62 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
+
       - name: Download Pages artifact
         uses: actions/download-artifact@v3
         with:
           name: github-pages
-          path: _site/
+          path: _site
 
       - name: Deploy to Pages
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           folder: _site
           target-folder: docs
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    needs: build
+    if: needs.build.outputs.release == 'true'
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ env.PYPI_PACKAGE }}
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download docgen artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: docgen-build
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.publish == 'TestPyPI'
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/${{ env.PYPI_PACKAGE }}
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download docgen artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: docgen-build
+          path: dist
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+        

doc/TODO.md

@@ -8,5 +8,8 @@
 - [x] API improvements (disable exporting, make it easier (possible?) to generate book for imported mods)
 - [ ] Unit test for mock addon book
 - [ ] Re-add edified wood recipe to [Common/src/main/resources/assets/hexcasting/patchouli_books/thehexbook/en_us/entries/items/edified.json](items/edified) when it actually exists
-- [ ] Language picker
-- [ ] Version picker
+- [x] Language
+- [x] Version
+  - [x] Don't delete sitemap markers
+  - [x] delete in dest, then copy, then traverse again to build sitemap from scratch
+- [ ] Dropdowns for ^

doc/src/hexdoc/hexdoc.py

@@ -104,6 +104,10 @@ class SitemapMarker(HexdocModel):
     lang: str
     path: str
 
+    @classmethod
+    def load(cls, path: Path):
+        return cls.model_validate_json(path.read_text("utf-8"))
+
 
 def main(args: Args | None = None) -> None:
     # allow passing Args for test cases, but parse by default

doc/src/hexdoc/hexdoc_merge.py

@@ -18,16 +18,16 @@ def strip_empty_lines(text: str) -> str:
 class Args(HexdocModel):
     """example: main.py properties.toml -o out.html"""
 
-    source: Path
-    dest: Path
+    src: Path
+    dst: Path
     release: bool
 
     @classmethod
     def parse_args(cls, args: Sequence[str] | None = None) -> Self:
         parser = ArgumentParser(allow_abbrev=False)
 
-        parser.add_argument("--source", type=Path, required=True)
-        parser.add_argument("--dest", type=Path, required=True)
+        parser.add_argument("--src", type=Path, required=True)
+        parser.add_argument("--dst", type=Path, required=True)
         parser.add_argument("--release", default=False)
 
         return cls.model_validate(vars(parser.parse_args(args)))
@@ -37,39 +37,34 @@ def main():
     args = Args.parse_args()
 
     # ensure at least the default language was built successfully
-    latest_default = args.source / "v" / "latest" / "index.html"
+    latest_default = args.src / "v" / "latest" / "index.html"
     if not latest_default.is_file():
         raise FileNotFoundError(latest_default)
 
-    args.dest.mkdir(parents=True, exist_ok=True)
+    args.dst.mkdir(parents=True, exist_ok=True)
 
+    # remove the book from the root of the destination since we're adding a new one now
     if args.release:
-        # remove current latest-released book in the destination
-        for path in args.dest.iterdir():
+        for path in args.dst.iterdir():
             if path.name not in ["v", "meta"]:
                 shutil.rmtree(path)
 
-    new_sitemap = defaultdict[str, dict[str, str]](dict)
-    for marker_path in args.source.rglob(MARKER_NAME):
-        # add new(?) version to the sitemap
-        marker = SitemapMarker.model_validate_json(marker_path.read_text("utf-8"))
-        new_sitemap[marker.version][marker.lang] = marker.path
+    # find all the marked directories in source and delete them from dest
+    for marker_path in args.src.rglob(MARKER_NAME):
+        dst_marker_dir = args.dst / marker_path.parent.relative_to(args.src)
+        shutil.rmtree(dst_marker_dir, ignore_errors=True)
 
-        # delete the corresponding directory in the destination
-        marker_dest_dir = args.dest / marker_path.parent.relative_to(args.source)
-        shutil.rmtree(marker_dest_dir, ignore_errors=True)
+    # that should be all the possible conflicts, so merge src into dst now
+    shutil.move(args.src / "*", args.dst)
 
-        marker_path.unlink()
+    # crawl the new tree to rebuild the sitemap
+    sitemap = defaultdict[str, dict[str, str]](dict)
 
-    sitemap_path = args.dest / "meta" / "sitemap.json"
+    for marker_path in args.dst.rglob(MARKER_NAME):
+        marker = SitemapMarker.load(marker_path)
+        sitemap[marker.version][marker.lang] = marker.path
 
-    if sitemap_path.is_file():
-        sitemap = json.loads(sitemap_path.read_text("utf-8")) | new_sitemap
-    else:
-        sitemap = new_sitemap
-
-    shutil.copytree(args.source, args.dest, dirs_exist_ok=True)
-    write_to_path(sitemap_path, json.dumps(sitemap))
+    write_to_path(args.dst / "meta" / "sitemap.json", json.dumps(sitemap))
 
 
 if __name__ == "__main__":