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

@@ -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

docs/modules/constants.rst

@@ -15,3 +15,8 @@ Constants
  :members:
  :undoc-members:
  :show-inheritance:
+
+.. autoclass:: pypdf.constants.UserAccessPermissions
+ :members:
+ :undoc-members:
+ :show-inheritance: