Documentation site redux

.github/workflows/ci.yml

@@ -1,5 +1,6 @@
+---
 name: CI
-on:
+'on':
   push:
     branches:
       - master
@@ -10,22 +11,24 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - name: ci/Checkout code
-      uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
-    - uses: actions/setup-python@db9987b4c1f10f0404fa60ee629f675fafbd6763 # v4.6.0
-      with:
-        python-version: '3.9'
-    - name: ci/Build
-      run: |
-        make python-deps
-        make html
-    - name: ci/Persist docs artifacts
-      uses: actions/upload-artifact@65d862660abb392b8c4a3d1195a2108db131dd05 # v3.1.2
-      with:
-        name: docs
-        path: build/html
-    - name: ci/Persist doc logs artifacts
-      uses: actions/upload-artifact@65d862660abb392b8c4a3d1195a2108db131dd05 # v3.1.2
-      with:
-        name: doc-logs
-        path: build/*.log
+      - name: ci/Checkout code
+        uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c  # v3.3.0
+      - uses: actions/setup-python@db9987b4c1f10f0404fa60ee629f675fafbd6763  # v4.6.0
+        with:
+          python-version: 3.9
+      - name: ci/Install dependencies
+        run: make python-deps
+      - name: ci/Run tests
+        run: TZ=UTC make test
+      - name: ci/Build docs
+        run: TZ=UTC make html
+      - name: ci/Persist docs artifacts
+        uses: actions/upload-artifact@65d862660abb392b8c4a3d1195a2108db131dd05  # v3.1.2
+        with:
+          name: docs
+          path: build/html
+      - name: ci/Persist doc logs artifacts
+        uses: actions/upload-artifact@65d862660abb392b8c4a3d1195a2108db131dd05  # v3.1.2
+        with:
+          name: doc-logs
+          path: build/*.log

.github/workflows/preview-env-fork.yml

@@ -78,7 +78,7 @@ jobs:
 
       - name: Build
         if: ${{ steps.label-checker.outputs.result == 'true' }}
-        run: make SPHINXOPTS="-j auto -D mm_url_path_prefix=/${{ steps.pr.outputs.id }}" html
+        run: make SPHINXOPTS="-j auto -D html_baseurl=http://mattermost-docs-preview-pulls.s3-website-us-east-1.amazonaws.com/${{ steps.pr.outputs.id }}" html
 
       - uses: shallwefootball/s3-upload-action@4350529f410221787ccf424e50133cbc1b52704e # v1.3.3
         name: Upload Preview Env

.github/workflows/preview-env.yml

@@ -30,7 +30,7 @@ jobs:
 
       - name: Build
         if: github.event.pull_request.head.repo.full_name == github.repository
-        run: make SPHINXOPTS="-j auto -D mm_url_path_prefix=/${{ steps.pr.outputs.id }}" html
+        run: make SPHINXOPTS="-j auto -D html_baseurl=http://mattermost-docs-preview-pulls.s3-website-us-east-1.amazonaws.com/${{ github.event.number }}" html
 
       - uses: shallwefootball/s3-upload-action@4350529f410221787ccf424e50133cbc1b52704e # v1.3.3
         name: Upload Preview Env

Makefile

@@ -10,6 +10,19 @@ WARNINGSFILE    = $(BUILDDIR)/warnings.log
 SPHINXOPTS      ?= -j auto
 SPHINXBUILD     ?= pipenv run sphinx-build
 SPHINXAUTOBUILD ?= pipenv run sphinx-autobuild
+AUTOBUILDOPTS   ?= -D=html_baseurl=http://127.0.0.1:8000
+
+# If we're not on Windows, check to see if 'mm_url_path_prefix' is included in SPHINXOPTS.
+# If it is included, extract the PR ID from the prefix and set the html_baseurl config
+# option to the preview environment.
+ifneq ($(OS),Windows_NT)
+ifeq ($(findstring mm_url_path_prefix,$(SPHINXOPTS)),mm_url_path_prefix)
+PATH_PREFIX = $(shell echo "$(SPHINXOPTS)" | grep -Eo 'mm_url_path_prefix=\/([0-9]+)' | cut -d / -f 2)
+SPHINXOPTS2 = $(SPHINXOPTS) -D html_baseurl=http://mattermost-docs-preview-pulls.s3-website-us-east-1.amazonaws.com/$(PATH_PREFIX)
+else
+SPHINXOPTS2 = $(SPHINXOPTS)
+endif
+endif
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -22,7 +35,7 @@ endif
 # Install necessary dependencies for the CI build pipeline.
 # NOTE: if the version of Python used to build the docs changes, update the `pipenv` command below accordingly.
 python-deps:
-	pip install pipenv==2022.12.19
+	pip install pipenv==2023.11.15
 	pipenv install --dev --clear --deploy --python 3.9
 
 test:
@@ -32,10 +45,10 @@ test:
 livehtml:
 ifeq ($(OS),Windows_NT)
 	@CMD /C IF NOT EXIST $(BUILDDIR) MD $(BUILDDIR)
-	@CMD /C $(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) $(O)
+	@CMD /C $(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) $(AUTOBUILDOPTS) $(O)
 else
 	@mkdir -p "$(BUILDDIR)"
-	@$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) $(O)
+	@$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) $(AUTOBUILDOPTS) $(O)
 endif
 
 # Run `make linkcheck` to check external links
@@ -71,5 +84,5 @@ ifeq ($(OS),Windows_NT)
 	@CMD /C $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -w "$(WARNINGSFILE)" 2>NUL
 else
 	@mkdir -p "$(BUILDDIR)"
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 2>>"$(WARNINGSFILE)"
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS2) $(O) 2>>"$(WARNINGSFILE)"
 endif

Pipfile

@@ -8,44 +8,54 @@ name = "pypi"
 # Amazon AWS Universal CLI environment (https://aws.amazon.com/cli/)
 # Release notes: https://github.com/aws/aws-cli/blob/develop/CHANGELOG.rst
 # Repo: https://github.com/aws/aws-cli
-awscli = "==1.29.38"
+awscli = "==1.32.8"
 #
-# PyTest testing framework (https://docs.pytest.org/en/7.2.x/)
-pytest = "==7.2.0"
+# PyTest testing framework (https://docs.pytest.org/en/7.4.x/)
+pytest = "==7.4.2"
+#
+# exceptiongroup: Backport of PEP-654 Exception groups to Python <3.11
+exceptiongroup = {version = "*", markers = "python_version < '3.11'"}
+#
+# Black: A Python source formatter
+black = "==23.10.1"
+#
+# Docutils Stubs
+docutils-stubs = "==0.0.22"
 
 [packages]
 #
 # Sphinx (https://www.sphinx-doc.org)
 # Release notes: https://www.sphinx-doc.org/en/master/changes.html
 # Repo: https://github.com/sphinx-doc/sphinx
-sphinx = "==4.4.0"
+sphinx = "==7.2.6"
 #
-# ReadTheDocs Theme (https://sphinx-rtd-theme.readthedocs.io/)
-# Release notes: https://github.com/readthedocs/sphinx_rtd_theme/blob/master/docs/changelog.rst
-# Repo: https://github.com/readthedocs/sphinx_rtd_theme
-sphinx-rtd-theme = "==1.0.0"
+# Furo Theme (https://github.com/pradyunsg/furo)
+furo = "==2023.9.10"
 #
 # MyST Parser (https://myst-parser.readthedocs.io/en/latest/)
 # Release notes: https://myst-parser.readthedocs.io/en/latest/develop/_changelog.html
 # Repo: https://github.com/executablebooks/myst-parser
-myst-parser = "==0.15.1"
+myst-parser = "==2.0.0"
 #
 # Sphinx Autobuild (https://github.com/executablebooks/sphinx-autobuild)
 # Repo: https://github.com/executablebooks/sphinx-autobuild
 sphinx-autobuild = "==2021.3.14"
 #
 # Tabbed views for Sphinx (https://sphinx-tabs.readthedocs.io/)
 # Repo: https://github.com/executablebooks/sphinx-tabs
-sphinx-tabs = "==3.4.0"
+#sphinx-tabs = "==3.4.0"
 #
 # Setuptools; used by sphinx-tabs
 # Repo: https://github.com/pypa/setuptools
 setuptools = "==68.2.2"
 #
 # Add a "copy" button to code blocks in Sphinx (https://sphinx-copybutton.readthedocs.io/en/latest/)
 # Repo: https://github.com/executablebooks/sphinx-copybutton
-sphinx-copybutton = "0.5.0"
+sphinx-copybutton = "==0.5.2"
 #
 # Python importlib metadata library; used by Sphinx
 # Repo: https://github.com/python/importlib_metadata
 importlib-metadata = "==4.12.0"
+#
+# Tabbed views for Sphinx (https://github.com/pradyunsg/sphinx-inline-tabs)
+sphinx-inline-tabs = "==2023.04.21"