DOC: implement multi-version in main

.github/workflows/nightly-doc-build.yml

@@ -25,14 +25,6 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      # used for documentation deployment
-      - name: Get Bot Application Token
-        id: get_workflow_token
-        uses: peter-murray/workflow-application-token-action@v2
-        with:
-          application_id: ${{ secrets.BOT_APPLICATION_ID }}
-          application_private_key: ${{ secrets.BOT_APPLICATION_PRIVATE_KEY }}
-
       - name: Setup Python
         uses: actions/setup-python@v4.3.0
         with:
@@ -74,15 +66,6 @@ jobs:
           pip install .[doc]
           xvfb-run make -C doc html
 
-      - name: Deploy
-        uses: JamesIves/github-pages-deploy-action@v4.4.1
-        with:
-          repository-name: pyansys/pymapdl-dev-docs
-          token: ${{ steps.get_workflow_token.outputs.token }}
-          branch: gh-pages
-          folder: doc/build/html
-          clean: true
-
       - name: Display files structure
         if: always()
         run: |
@@ -141,4 +124,4 @@ jobs:
           steps: ${{ toJson(steps) }}
           overwrite: "{
             title: `${workflow} failed.`, 
-            }"
+            }"

doc/Makefile

@@ -5,8 +5,8 @@
 SPHINXOPTS    = -j auto
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
-LINKCHECKDIR  = build/linkcheck
+BUILDDIR      = _build
+LINKCHECKDIR  = $(BUILDDIR)/linkcheck
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -37,8 +37,8 @@ clean-except-examples:
 pdf:
 	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	python validate_png.py  # clean-up GIFs mislabeled as PNG
-	cd build/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
-	(test -f build/latex/*.pdf && echo pdf exists) || exit 1
+	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
+	(test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1
 
 checklinks:
 	$(SPHINXBUILD) -b linkcheck $(SPHINXOPTS) $(LINKCHECKDIR)
@@ -53,12 +53,12 @@ deploy:
 	@echo "This overwrites the history of gh-pages."
 	@echo "Are you sure? [y/N] " && read ans && [ $${ans:-N} = y ]
 	@echo "Deploying..."
-	touch build/html/.nojekyll
+	touch $(BUILDDIR)/html/.nojekyll
 	echo "mapdl.docs.pyansys.com" >> build/html/CNAME
-	cd build/html && git init
-	cd build/html && git add .
-	cd build/html && git checkout -b gh-pages
-	cd build/html && git commit -am "manual build"
-	cd build/html && git remote add origin https://github.com/pyansys/pymapdl-docs
-	cd build/html && git push -u origin gh-pages --force
-	rm -rf build/html/.git
+	cd $(BUILDDIR)/html && git init
+	cd $(BUILDDIR)/html && git add .
+	cd $(BUILDDIR)/html && git checkout -b gh-pages
+	cd $(BUILDDIR)/html && git commit -am "manual build"
+	cd $(BUILDDIR)/html && git remote add origin https://github.com/pyansys/pymapdl-docs
+	cd $(BUILDDIR)/html && git push -u origin gh-pages --force
+	rm -rf $(BUILDDIR)/html/.git

doc/make.bat

@@ -8,7 +8,7 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
-set BUILDDIR=build
+set BUILDDIR=_build
 set LINKCHECKDIR=\%BUILDDIR%\linkcheck
 
 if "%1" == "" goto help

doc/source/conf.py

@@ -3,7 +3,7 @@
 import os
 import warnings
 
-from ansys_sphinx_theme import pyansys_logo_black
+from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
 import numpy as np
 import pyvista
 from sphinx_gallery.sorting import FileNameSortKey
@@ -45,6 +45,7 @@
 
 # The short X.Y version
 release = version = __version__
+cname = os.getenv("DOCUMENTATION_CNAME", "nocname.com")
 
 
 # -- General configuration ---------------------------------------------------
@@ -107,7 +108,7 @@
 }
 
 # Favicon
-html_favicon = "favicon.png"
+html_favicon = ansys_favicon
 
 # notfound.extension
 notfound_template = "404.rst"
@@ -205,6 +206,11 @@
             "icon": "fa fa-comment fa-fw",
         },
     ],
+    "switcher": {
+        "json_url": f"https://{cname}/release/versions.json",
+        "version_match": get_version_match(__version__),
+    },
+    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
 }
 
 html_context = {

doc/validate_png.py

@@ -9,7 +9,7 @@
 from PIL import Image
 
 this_path = os.path.dirname(os.path.abspath(__file__))
-check_path = os.path.join(this_path, "build", "latex")
+check_path = os.path.join(this_path, "_build", "latex")
 if not os.path.isdir(check_path):
     raise FileNotFoundError(f"Invalid path {check_path}")
 

pyproject.toml

@@ -66,7 +66,7 @@ doc = [
     "Sphinx==5.3.0",
     "ansys-dpf-core==0.7.0",
     "ansys-mapdl-reader==0.52.3",
-    "ansys-sphinx-theme==0.7.2",
+    "ansys-sphinx-theme==0.8.0",
     "grpcio==1.43.0",
     "imageio-ffmpeg==0.4.7",
     "imageio==2.22.4",