feat(docs): improve and automate quarto documentation workflow

This commit overhauls the Quarto documentation generation and CI process.

- Automates the documentation build and deployment via GitHub Actions.
- Implements Quarto's 'freeze' feature to significantly speed up builds by caching computational results.
- Adds a markdown linting job to the CI to ensure documentation quality.
- Fixes numerous docstrings and cross-reference links in the API documentation.
- Updates the Quarto configuration to correctly build the reference documentation and ignore build artifacts (, ).

Author: apoorvalal

.github/workflows/docs.yaml

@@ -42,12 +42,16 @@ jobs:
 
       - name: Render docs
         run: |
-          pixi run docs-render
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            pixi run docs-render -- --no-cache
+          else
+            pixi run docs-render
+          fi
 
       - name: Save docs artifact
         uses: actions/upload-artifact@v4
         with:
-          name: docs-html
+          name: docs-html-${{ matrix.python-version }}
           path: docs/_site
 
   publish-docs:
@@ -63,7 +67,7 @@ jobs:
       - name: Download docs artifact
         uses: actions/download-artifact@v4
         with:
-          name: docs-html
+          name: docs-html-3.12
           path: docs/_site
 
       - name: Publish docs to GitHub Pages
@@ -81,7 +85,7 @@ jobs:
       - name: Download docs artifact
         uses: actions/download-artifact@v4
         with:
-          name: docs-html
+          name: docs-html-3.12
           path: docs/_site
       - name: Upload docs artifact
         uses: actions/upload-artifact@v4

docs/.gitignore

@@ -1 +1,4 @@
-*.swp
+_site/
+.quarto/
+reference/
+*.swp

docs/_quarto.yml

@@ -1,6 +1,10 @@
 project:
   type: website
   output-dir: _site
+  freeze: auto
+
+exclude:
+  - "compare-fixest-pyfixest.qmd"
 
 metadata-files:
   - _sidebar.yml
@@ -43,8 +47,6 @@ website:
           text: "On Small Sample Corrections"
         - file: quantile-regression.qmd
           text: "Quantile Regression"
-        - text: "Compare fixest & PyFixest"
-          file: compare-fixest-pyfixest.qmd
         - text: "Compare Stata & PyFixest"
           file: stata-2-pyfixest.qmd
         - text: "PyFixest on the GPU"