Merge pull request #1164 from RonnyPfannschmidt/fix-docs-issues

documentaiton fixes

Author: RonnyPfannschmidt

.github/workflows/api-check.yml

@@ -34,5 +34,20 @@ jobs:
           pip install -e .[test]
 
       - name: Run griffe API check
+        id: griffe-check
         run: |
-          griffe check setuptools_scm -ssrc -f github
+          if griffe check setuptools_scm -ssrc -f github; then
+            echo "api_check_result=success" >> $GITHUB_OUTPUT
+          else
+            echo "api_check_result=warning" >> $GITHUB_OUTPUT
+            echo "API stability check detected changes but will not fail the build" >> $GITHUB_STEP_SUMMARY
+          fi
+
+      - name: Report API check result
+        if: steps.griffe-check.outputs.api_check_result == 'warning'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            core.warning('API stability check detected breaking changes. Please review the API changes above.')
+            core.summary.addRaw('⚠️ API Stability Warning: Breaking changes detected in the public API')
+            await core.summary.write()

CHANGELOG.md

@@ -33,6 +33,9 @@
 - add support for failing on missing submodules
 - fix #279: expand errors when scm can be found upwards and relative_to wasnt used
 - fix #577: introduce explicit scmversion node and short node
+- fix #1100: add workaround for readthedocs worktress to the docs
+- fix #790: document shallow fail for rtd
+- fix #474: expand version not found error message to provide clearer guidance about SETUPTOOLS_SCM_PRETEND_VERSION_FOR_* environment variables
 
 ## v8.3.1
 

docs/integrations.md

@@ -0,0 +1,50 @@
+# Integrations
+
+## ReadTheDocs
+
+### Avoid having a dirty Git index
+
+When building documentation on ReadTheDocs, file changes during the build process can cause setuptools-scm to detect a "dirty" working directory.
+
+To avoid this issue, ReadTheDocs recommends using build customization to clean the Git state after checkout:
+
+```yaml title=".readthedocs.yaml"
+version: 2
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+  jobs:
+    post_checkout:
+      # Avoid setuptools-scm dirty Git index issues
+      - git reset --hard HEAD
+      - git clean -fdx
+```
+
+This ensures a clean Git working directory before setuptools-scm detects the version, preventing unwanted local version components.
+
+
+
+Reference: [ReadTheDocs Build Customization - Avoid having a dirty Git index](https://docs.readthedocs.com/platform/stable/build-customization.html#avoid-having-a-dirty-git-index)
+
+
+### Enforce fail on shallow repositories
+
+ReadTheDocs may sometimes use shallow Git clones that lack the full history needed for proper version detection. You can use setuptools-scm's environment variable override system to enforce `fail_on_shallow` when building on ReadTheDocs:
+
+```yaml title=".readthedocs.yaml"
+version: 2
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+  jobs:
+    post_checkout:
+      # Avoid setuptools-scm dirty Git index issues
+      - git reset --hard HEAD
+      - git clean -fdx
+      # Enforce fail_on_shallow for setuptools-scm
+      - export SETUPTOOLS_SCM_OVERRIDES_FOR_${READTHEDOCS_PROJECT//-/_}='{scm.git.pre_parse="fail_on_shallow"}'
+```
+
+This configuration uses the `SETUPTOOLS_SCM_OVERRIDES_FOR_${NORMALIZED_DIST_NAME}` environment variable to override the `scm.git.pre_parse` setting specifically for your project when building on ReadTheDocs, forcing setuptools-scm to fail with a clear error if the repository is shallow.

mkdocs.yml

@@ -5,6 +5,7 @@ nav:
   - usage.md
   - customizing.md
   - config.md
+  - integrations.md
   - extending.md
   - overrides.md
   - changelog.md