diff --git a/.gitignore b/.gitignore
index 7683d902..c2a2ef40 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,8 +7,6 @@ node_modules
 dist
 docs/_build
 docs/build
-docs/source/_static/rest-api
-docs/source/rbac/scope-table.md
 docs/source/reference/metrics.md
 
 .ipynb_checkpoints
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 58f2ee14..0fdf7ea9 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -33,7 +33,7 @@ repos:
     rev: v4.0.0-alpha.8
     hooks:
       - id: prettier
-        exclude: .*/templates/.*
+        exclude: .*/templates/.*|docs/source/_static/rest-api.yml|docs/source/rbac/scope-table.md
 
   # autoformat HTML templates
   - repo: https://github.com/djlint/djLint
@@ -56,3 +56,16 @@ repos:
       - id: requirements-txt-fixer
       - id: check-case-conflict
       - id: check-executables-have-shebangs
+
+  # source docs: rest-api.yml and scope-table.md are autogenerated
+  - repo: local
+    hooks:
+      - id: update-api-and-scope-docs
+        name: Update rest-api.yml and scope-table.md based on scopes.py
+        language: python
+        additional_dependencies: ["pytablewriter", "ruamel.yaml"]
+        entry: python docs/source/rbac/generate-scope-table.py
+        args:
+          - --update
+        files: jupyterhub/scopes.py
+        pass_filenames: false
diff --git a/docs/Makefile b/docs/Makefile
index 6be01454..b824651f 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -35,7 +35,7 @@ help:
 # - NOTE: If the pre-requisites for the html target is updated, also update the
 #         Read The Docs section in docs/source/conf.py.
 #
-html: metrics scopes
+html: metrics
 	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@@ -44,10 +44,6 @@ metrics: source/reference/metrics.md
 source/reference/metrics.md:
 	python3 generate-metrics.py
 
-scopes: source/rbac/scope-table.md
-source/rbac/scope-table.md:
-	python3 source/rbac/generate-scope-table.py
-
 
 # Manually added targets - related to development
 # ----------------------------------------------------------------------------
@@ -56,7 +52,7 @@ source/rbac/scope-table.md:
 # - requires sphinx-autobuild, see
 #   https://sphinxcontrib-spelling.readthedocs.io/en/latest/
 # - builds and rebuilds html on changes to source, but does not re-generate
-#   metrics/scopes files
+#   metrics files
 # - starts a livereload enabled webserver and opens up a browser
 devenv: html
 	sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html"
diff --git a/docs/source/rbac/scope-table.md b/docs/source/rbac/scope-table.md
new file mode 100644
index 00000000..e69de29b
diff --git a/jupyterhub/scopes.py b/jupyterhub/scopes.py
index ef75c915..0fe1961e 100644
--- a/jupyterhub/scopes.py
+++ b/jupyterhub/scopes.py
@@ -31,8 +31,11 @@ from tornado.log import app_log
 from . import orm, roles
 from ._memoize import DoNotCache, FrozenDict, lru_cache_key
 
-"""when modifying the scope definitions, make sure that `docs/source/rbac/generate-scope-table.py` is run
-   so that changes are reflected in the documentation and REST API description."""
+"""when modifying the scope definitions
+   `docs/source/rbac/generate-scope-table.py` must be run
+   so that changes are reflected in the documentation and REST API description.
+   `pre-commit run -a` should automatically take care of this.
+   """
 scope_definitions = {
     '(no_scope)': {'description': 'Identify the owner of the requesting entity.'},
     'self': {