DOC: implement multi-doc in v0.63

.github/workflows/ci.yml

@@ -16,6 +16,7 @@ env:
   PYANSYS_OFF_SCREEN: True
   DOCKER_PACKAGE: ghcr.io/pyansys/pymapdl/mapdl
   DOCKER_IMAGE_VERSION_DOCS_BUILD: v22.2.0
+  DOCUMENTATION_CNAME: "mapdl.docs.pyansys.com"
   # Following env vars when changed will "reset" the mentioned cache,
   # by changing the cache file name. It is rendered as ...-v%RESET_XXX%-...
   # You should go up in number, if you go down (or repeat a previous value)
@@ -117,15 +118,6 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      # used for documentation deployment
-      - name: Get Bot Application Token
-        if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
-        id: get_workflow_token
-        uses: peter-murray/workflow-application-token-action@v1
-        with:
-          application_id: ${{ secrets.BOT_APPLICATION_ID }}
-          application_private_key: ${{ secrets.BOT_APPLICATION_PRIVATE_KEY }}
-
       - name: Setup Python
         uses: actions/[email protected]
         with:
@@ -186,7 +178,7 @@ jobs:
       - name: Cache docs build directory
         uses: actions/cache@v3
         with:
-          path: doc/build
+          path: doc/_build
           key: doc-build-v${{ env.RESET_DOC_BUILD_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }}
           restore-keys: |
             doc-build-v${{ env.RESET_DOC_BUILD_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}
@@ -201,43 +193,28 @@ jobs:
 
       - name: Install Docs Build Requirements
         run: |
-          pip install -r requirements/requirements_docs.txt
+          pip install -r requirements/requirements_doc.txt
 
       - name: Build Documentation
         run: |
           xvfb-run make -C doc html SPHINXOPTS="-j auto -W --keep-going"
 
-      - name: Zip documentation
-        run: |
-          cd doc/build/html
-          zip -r PyMAPDL_documentation.zip *
-
       - name: Upload HTML Documentation
         uses: actions/upload-artifact@v3
         with:
-          name: HTML-Documentation
-          path: doc/build/html/PyMAPDL_documentation.zip
+          name: documentation-html
+          path: doc/_build/html
           retention-days: 7
 
-      - name: Deploy
-        if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
-        uses: JamesIves/[email protected]
-        with:
-          repository-name: pyansys/pymapdl-docs
-          token: ${{ steps.get_workflow_token.outputs.token }}
-          branch: gh-pages
-          folder: doc/build/html
-          clean: true
-
       - name: Build PDF Documentation
         working-directory: doc
         run: make pdf
 
       - name: Upload PDF Documentation
         uses: actions/upload-artifact@v3
         with:
-          name: PDF-Documentation
-          path: doc/build/latex/pymapdl*.pdf
+          name: documentation-pdf
+          path: doc/_build/latex/pymapdl*.pdf
           retention-days: 7
 
       - name: Display files structure
@@ -266,7 +243,7 @@ jobs:
       - name: Tar logs
         if: always()
         run: |
-          cp -f doc/build/latex/*.log ./logs-build-docs/
+          cp -f doc/_build/latex/*.log ./logs-build-docs/
           cp log.txt ./logs-build-docs/
           tar cvzf ./logs-build-docs.tgz ./logs-build-docs
 
@@ -284,7 +261,7 @@ jobs:
       - name: List main files
         if: always()
         run: |
-          if compgen -G 'doc/build/latex/*.log' > /dev/null ;then for f in doc/build/latex/*.log; do echo "::group:: Output latex log file $f" && cat $f && echo "::endgroup::" ; done; fi
+          if compgen -G 'doc/_build/latex/*.log' > /dev/null ;then for f in doc/_build/latex/*.log; do echo "::group:: Output latex log file $f" && cat $f && echo "::endgroup::" ; done; fi
           if compgen -G './logs-build-docs/*.err' > /dev/null ;then for f in ./logs-build-docs/*.err; do echo "::group:: Error file $f" && cat $f && echo "::endgroup::" ; done; fi
           if compgen -G './logs-build-docs/*.log' > /dev/null ;then for f in ./logs-build-docs/*.log; do echo "::group:: Log file $f" && cat $f && echo "::endgroup::" ; done; fi
           if compgen -G './logs-build-docs/*.out' > /dev/null ;then for f in ./logs-build-docs/*.out; do echo "::group:: Output file $f" && cat $f && echo "::endgroup::" ; done; fi
@@ -454,3 +431,17 @@ jobs:
           overwrite: "{
             title: `Release FAILED!`,
             }"
+
+  upload_docs_release:
+    name: "Upload release documentation"
+    if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
+    runs-on: ubuntu-latest
+    needs: [Release]
+    steps:
+      - name: Deploy the stable documentation
+        uses: pyansys/actions/doc-deploy-stable@v2
+        with:
+          cname: ${{ env.DOCUMENTATION_CNAME }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          python-version: '3.10'
+

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

@@ -19,14 +19,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@v1
-        with:
-          application_id: ${{ secrets.BOT_APPLICATION_ID }}
-          application_private_key: ${{ secrets.BOT_APPLICATION_PRIVATE_KEY }}
-
       - name: Setup Python
         uses: actions/[email protected]
         with:
@@ -65,15 +57,6 @@ jobs:
           pip install -r requirements/requirements_docs.txt
           xvfb-run make -C doc html
 
-      - name: Deploy
-        uses: JamesIves/[email protected]
-        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: |
@@ -133,4 +116,4 @@ jobs:
           steps: ${{ toJson(steps) }}
           overwrite: "{
             title: `${workflow} failed.`, 
-            }"
+            }"

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
     "--force-sort-within-sections",
     "--skip-glob", "*__init__.py",
     ]
-- repo: https://gitlab.com/PyCQA/flake8
+- repo: https://github.com/PyCQA/flake8
   rev: 3.9.2
   hooks:
   - id: flake8

doc/Makefile

@@ -5,7 +5,8 @@
 SPHINXOPTS    = -j auto
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = _build
+LINKCHECKDIR  = $(BUILDDIR)/linkcheck
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -36,8 +37,13 @@ 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)
+	@echo
+	@echo "Check finished. Report is in $(LINKCHECKDIR)."
 
 # manually deploy to https://github.com/pyansys/pymapdl-docs
 # WARNING: Use with care as this overwrites history of gh-pages
@@ -47,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
-	echo "mapdldocs.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
+	touch $(BUILDDIR)/html/.nojekyll
+	echo "mapdl.docs.pyansys.com" >> build/html/CNAME
+	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,8 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
-set BUILDDIR=build
+set BUILDDIR=_build
+set LINKCHECKDIR=\%BUILDDIR%\linkcheck
 
 if "%1" == "" goto help
 if "%1" == "clean" goto clean

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 ---------------------------------------------------
@@ -106,7 +107,7 @@
 }
 
 # Favicon
-html_favicon = "favicon.png"
+html_favicon = ansys_favicon
 
 # notfound.extension
 notfound_template = "404.rst"
@@ -188,6 +189,18 @@
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
     ],
+    "icon_links": [
+        {
+            "name": "Support",
+            "url": "https://github.com/pyansys/pymapdl/discussions",
+            "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"],
 }
 
 # -- Options for HTMLHelp output ---------------------------------------------

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}")
 

requirements/requirements_docs.txt → requirements/requirements_doc.txt

@@ -1,6 +1,6 @@
 Sphinx==5.1.1
 ansys-mapdl-reader==0.52.0
-ansys-sphinx-theme==0.5.2
+ansys-sphinx-theme==0.8.0
 grpcio==1.43.0
 imageio-ffmpeg==0.4.7
 imageio==2.21.2