Documentation site redux (mattermost#6751)

* Apply changes from redux proof-of-concept; Update tests; Add workaround for furo template rendering; Update README

* Re-add importlib-metadata dependency for Sphinx on Python 3.9

* Removed ..contents:: & deleted archived files

* Build warnings & error fixes

* Fix build warnings/errors & formatting

* Applied note formatting

* Port jQuery version of feedback widget to using the JS DOM; Override furo's page layout to add feedback widget; Remove feedback widget code from myscript-v1.js

* Update Pipfile.lock after re-locking

* Upgrade sphinx-tabs to 3.4.4

* Fix visibility of confirmation popup after submitting feedback

* Replaced sphinx-tabs with sphinx_inline_tabs

* Comment-out sphinx-tabs reference and re-generate lock file to fix dependency issue

* Move redirects section of conf.py higher up in the file to mitigate merge conflicts with master

* Re-add commented-out version settings to help mitigate merge conflicts with master

* Update commented-out version to help mitigate merge conflicts with master

* Initial incomplete pass at migrating custom search to Sphinx 7

* Remove stock Sphinx searchtols script; Remove v1 searchtools script; Finish refactoring v4 searchtools to v7

* Remove unused templates

* Load search indexes when DOM has finished loading

* Update awscli dependency; Add exceptiongroup dependency for python older than 3.11; Add docutils-stubs to dev dependencies; Update default pipenv version to latest; Update CI pipeline script to run tests before building and to fix a Python TZ issue

* Start new styles setup

* Start scaffolding for redesign project

* Rename redsign files. Add conditional for index css.

* UX UI Updates

* Updating css

* Updating css

* Updating badges

* Updating css

* Updating css

* Updating docs

* Updating docs site

* Update nav structure and adjust homepage css

* Delete old css and js files

* Update styles when notification banner is active

* Update notification banner content

* Added :class: theme-icon to all Compass Icon SVG refs

* Removed legacy .. tabs:: and .. contents:: directives

* Fixed build warnings/errors

* Various UI Fixes

* Release readiness & build fixes

* Modify redirects extension to use html_baseurl instead of hardcoded docs.mattermost.com and to remove the use of mm_url_path_prefix in favour of using Sphinx's html_baseurl; Update tests; Update Makefile to use custom html_baseurl when running livehtml target; Update GitHub workflows to use html_baseurl for preview environments

* Add script for one-time conversion of rST links to doc and ref directives

* Small fixes to one-time link conversion script

* Move one-time conversion script into root so it can access conf.py easily; Exclude orphan files and urls with particular characteristics

* Use furo's built-in base.html template

* Remove extraneous templates; Add comment to page and custom-index template regarding furo base templates

* More robust ignoring of directories; Resolve redirects fully before constructing a directive

* [REFACTOR] Rewrite rST links into inline doc and ref directives where possible to allow html_baseurl to work correctly

* Temporary workaround to allow preview environments to use the correct html_baseurl

* Table formatting fixes

* Converting internal HTML links > Sphinx directives

* Converting internal HTML links > Sphinx directives

* Converting internal HTML links > Sphinx directives

* Replaced ambiguous deploy badges

* Updating UI

* Updated Cloud signup URL

* Broken link fix

* Extract Mattermost theme modifications into new page.html, leaving the previous page-v1.html around temporarily; Enable Edit in GitHub functionality in conf.py; Remove old RTD theme config for Edit in GitHub

* Hid legacy changelogs & gencert from search results to improve results

* Converting internal HTML links > Sphinx directives

* Process hardcoded docs.mattermost.com links and exclude links that cross line boundaries

* [REFACTOR] Migrate hardcoded docs.mattermost.com rST links to doc and ref roles

* Updating thermotoer to allow multiple feedback

* Table syntax fixes & Converting internal HTML links > Sphinx directives

* Add Google Tag Manager functionality; Remove commented-out search v1 div from custom-nav.html

* Add GTM to custom index

* Update notification bar with webinar deets

* Fixed broken link

* Fix notification banner details

---------

Co-authored-by: Carrie Warner (Mattermost) <[email protected]>
Co-authored-by: Mattermost Build <[email protected]>
Co-authored-by: emdecr <[email protected]>
Co-authored-by: Asaad Mahmood <[email protected]>

Author: 5 people

.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"