Use actions/deploy-pages

.github/workflows/build_docs.yml

@@ -6,14 +6,14 @@ on:
   workflow_dispatch:
 
 jobs:
-  build_docs:
+  build:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
+
     steps:
     - uses: actions/checkout@v3
 
-    - uses: actions/setup-python@v4
+    - name: Set up Python
+      uses: actions/setup-python@v4
       with:
         python-version: "3.11"
 
@@ -21,21 +21,22 @@ jobs:
       run: pip install .
 
     - name: Generate file
-      run: hexdoc doc/properties.toml -o index.html.uncommitted --ci
+      run: hexdoc doc/properties.toml --ci -o out
 
-    - name: Check out gh-pages
-      uses: actions/checkout@v3
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v2
       with:
-        clean: false
-        ref: gh-pages
+        path: ./out
+  
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
 
-    - name: Overwrite file and commmit
-      run: |
-          mv index.html.uncommitted index.html
-          git config user.name "HexDoc Bot"
-          git config user.email "noreply@github.com"
-          git add index.html
-          git diff-index --quiet HEAD || git commit -m "Update web book from $GITHUB_REF"
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
 
-    - name: Upload changes
-      run: git push
+    steps:
+      - name: Deploy to Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

doc/.gitignore

@@ -1,2 +1 @@
-/*.html
 /src/hexdoc/_export/generated/

doc/src/hexdoc/hexdoc.py

@@ -29,7 +29,7 @@ class Args(HexdocModel):
     """example: main.py properties.toml -o out.html"""
 
     properties_file: Path
-    output_file: Path | None
+    output_dir: Path | None
     export_only: bool
     verbose: int
     ci: bool
@@ -43,12 +43,12 @@ class Args(HexdocModel):
         parser.add_argument("--ci", action="store_true")
 
         group = parser.add_mutually_exclusive_group(required=True)
-        group.add_argument("--output_file", "-o", type=Path)
+        group.add_argument("--output_dir", "-o", type=Path)
         group.add_argument("--export-only", "-e", action="store_true")
 
         return cls.model_validate(vars(parser.parse_args(args)))
 
-    @field_validator("properties_file", "output_file", mode="after")
+    @field_validator("properties_file", "output_dir", mode="after")
     def _resolve_path(cls, value: Path | None):
         # make paths absolute because we're cd'ing later
         match value:
@@ -63,7 +63,7 @@ class Args(HexdocModel):
             self.verbose = True
 
         # exactly one of these must be truthy (should be enforced by group above)
-        assert bool(self.output_file) != self.export_only
+        assert bool(self.output_dir) != self.export_only
 
         return self
 
@@ -109,7 +109,7 @@ def main(args: Args | None = None) -> None:
 
         if args.export_only:
             return
-        assert args.output_file
+        assert args.output_dir
 
         # set up Jinja environment
         env = SandboxedEnvironment(
@@ -144,7 +144,8 @@ def main(args: Args | None = None) -> None:
             )
         )
 
-        args.output_file.write_text(docs, "utf-8")
+        args.output_dir.mkdir(parents=True, exist_ok=True)
+        (args.output_dir / "index.html").write_text(docs, "utf-8")
 
 
 if __name__ == "__main__":