Add docs validation to release process (#6967)

* Add ci stage to test for broken links in documentation

* Add docs validation to release process

* Update .github/workflows/main.yml

* Update .github/workflows/main.yml

---------

Co-authored-by: Ryan P Kilby <[email protected]>
Co-authored-by: Asif Saif Uddin <[email protected]>

Author: 3 people

.github/workflows/main.yml

@@ -56,3 +56,27 @@ jobs:
     - name: Upload coverage
       run: |
         codecov -e TOXENV,DJANGO
+
+  test-docs:
+    name: Test documentation links
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v3
+
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Install dependencies
+      run: pip install -r requirements/requirements-documentation.txt
+    
+    # Start mkdocs server and wait for it to be ready
+    - run: mkdocs serve &
+    - run: WAIT_TIME=0 && until nc -vzw 2 localhost 8000 || [ $WAIT_TIME -eq 5 ]; do sleep $(( WAIT_TIME++ )); done
+    - run: if [ $WAIT_TIME == 5 ]; then echo cannot start mkdocs server on http://localhost:8000; exit 1; fi
+    
+    - name: Check links
+      continue-on-error: true
+      run: pylinkvalidate.py -P http://localhost:8000/
+  
+    - run: echo "Done"

docs/community/project-management.md

@@ -112,6 +112,9 @@ The following template should be used for the description of the issue, and serv
         - [ ] `docs` Python & Django versions
     - [ ] Update the translations from [transifex](https://www.django-rest-framework.org/topics/project-management/#translations).
     - [ ] Ensure the pull request increments the version to `*.*.*` in [`restframework/__init__.py`](https://github.com/encode/django-rest-framework/blob/master/rest_framework/__init__.py).
+    - [ ] Ensure documentation validates
+        - Build and serve docs `mkdocs serve`
+        - Validate links `pylinkvalidate.py -P http://127.0.0.1:8000`
     - [ ] Confirm with @tomchristie that release is finalized and ready to go.
     - [ ] Ensure that release date is included in pull request.
     - [ ] Merge the release pull request.

requirements/requirements-documentation.txt

@@ -1,3 +1,6 @@
 # MkDocs to build our documentation.
 mkdocs>=1.1.2,<1.2
 jinja2>=2.10,<3.1.0 # contextfilter has been renamed
+
+# pylinkvalidator to check for broken links in documentation.
+pylinkvalidator==0.3