From 23a5a490f2b7c651856f56efc31e6ec785bf13c7 Mon Sep 17 00:00:00 2001
From: Stefan <96178532+stefan6419846@users.noreply.github.com>
Date: Wed, 17 Jan 2024 23:05:32 +0100
Subject: [PATCH] DEV: Fail on Sphinx issues (#2405)

This adds a code style check to avoid unexpectedly shipping docs/docstrings which cause issues.

Options (the long names are only part of the upcoming 7.3 release), based upon https://www.sphinx-doc.org/en/master/man/sphinx-build.html:

  * `-n`: Report warnings for missing references.
  * `-W`: Turn warnings into errors and stop at first violation.
  * `--keep-going`: Improve `-W` by collecting all violations and only failing at the end.
  * `-T`: Display the full traceback on actual errors.
  * `-b html`: Build HTML pages.
  * `docs`: Source directory.
  * `build/sphinx/html`: Target directory.

Fixes #2402
---
 .github/workflows/github-ci.yaml | 4 ++++
 docs/modules/constants.rst       | 5 +++++
 2 files changed, 9 insertions(+)

diff --git a/.github/workflows/github-ci.yaml b/.github/workflows/github-ci.yaml
index 7d0f1426c..085e86a5d 100644
--- a/.github/workflows/github-ci.yaml
+++ b/.github/workflows/github-ci.yaml
@@ -164,6 +164,10 @@ jobs:
     - name: Test with mypy
       run : |
         mypy pypdf
+    - name: Test docs build
+      run: |
+        pip install -r requirements/docs.txt
+        sphinx-build -n -W --keep-going -T -b html docs build/sphinx/html
 
   package:
     name: Build & verify package
diff --git a/docs/modules/constants.rst b/docs/modules/constants.rst
index d5d31563b..37f991303 100644
--- a/docs/modules/constants.rst
+++ b/docs/modules/constants.rst
@@ -15,3 +15,8 @@ Constants
     :members:
     :undoc-members:
     :show-inheritance:
+
+.. autoclass:: pypdf.constants.UserAccessPermissions
+    :members:
+    :undoc-members:
+    :show-inheritance: