DOC: implement multi-doc in v0.62 (#1678)

* MAINT: rename requirements_docs.txt -> requirements_doc.txt

* DOC: update to ansys-sphinx-theme

* DOC: update conf.py file

* DOC: rename build to _build dir

* CI: update

* FIX: do not use latest pyvista

* CI: deploy only stable

* FIX: pyvista aliasing command

* FIX: script for validating images

Author: jorgepiloto

.github/workflows/ci.yml

@@ -14,6 +14,7 @@ env:
   PYMAPDL_DB_PORT: 21001  # default won't work on GitHub runners
   PYMAPDL_START_INSTANCE: FALSE
   PYANSYS_OFF_SCREEN: True
+  DOCUMENTATION_CNAME: "mapdl.docs.pyansys.com"
   DOCKER_PACKAGE: ghcr.io/pyansys/pymapdl/mapdl
   DOCKER_IMAGE_VERSION_DOCS_BUILD: v21.2.1
   # Following env vars when changed will "reset" the mentioned cache,
@@ -27,6 +28,10 @@ env:
   RESET_AUTOSUMMARY_CACHE: 0
   PACKAGE_NAME: PyMAPDL
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
 
   stylecheck:
@@ -197,43 +202,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@v2
         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@v2
         with:
-          name: PDF-Documentation
-          path: doc/build/latex/pymapdl*.pdf
+          name: documentation-pdf
+          path: doc/_build/latex/pymapdl*.pdf
           retention-days: 7
 
   build_test:
@@ -359,3 +349,16 @@ 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'

.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,7 @@
 SPHINXOPTS    = -j auto
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -36,8 +36,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
 
 # manually deploy to https://github.com/pyansys/pymapdl-docs
 # WARNING: Use with care as this overwrites history of gh-pages
@@ -47,12 +47,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 "mapdldocs.pyansys.com" >> $(BUILDDIR)/html/CNAME
+	cd $(BUILDIR)/html && git init
+	cd $(BUILDIR)/html && git add .
+	cd $(BUILDIR)/html && git checkout -b gh-pages
+	cd $(BUILDIR)/html && git commit -am "manual build"
+	cd $(BUILDIR)/html && git remote add origin https://github.com/pyansys/pymapdl-docs
+	cd $(BUILDIR)/html && git push -u origin gh-pages --force
+	rm -rf $(BUILDDIR)/html/.git

doc/source/conf.py

@@ -3,8 +3,8 @@
 import os
 import warnings
 
+from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
 import numpy as np
-from pyansys_sphinx_theme import pyansys_logo_black
 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"
@@ -179,12 +180,17 @@
 
 # -- Options for HTML output -------------------------------------------------
 html_short_title = html_title = "PyMAPDL"
-html_theme = "pyansys_sphinx_theme"
+html_theme = "ansys_sphinx_theme"
 html_logo = pyansys_logo_black
 html_theme_options = {
     "github_url": "https://github.com/pyansys/pymapdl",
     "show_prev_next": False,
     "show_breadcrumbs": True,
+    "switcher": {
+        "json_url": f"https://{cname}/release/versions.json",
+        "version_match": get_version_match(__version__),
+    },
+    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
     ],

doc/source/examples/technology_showcase_examples/techdemo-1/ex_0-tecbrakesqueal.rst

@@ -220,7 +220,7 @@ Start this example by launching MAPDL and loading the model.
    pyvista.global_theme.background = 'white'
    pyvista.global_theme.window_size = [600, 400]
    pyvista.global_theme.axes.show = True
-   pyvista.global_theme.antialiasing = True
+   pyvista.global_theme.anti_aliasing = "fxaa"
    pyvista.global_theme.show_scalar_bar = True
 
    from ansys.mapdl.core import examples

doc/source/examples/technology_showcase_examples/techdemo-28/ex_28-tecfricstir.rst

@@ -121,7 +121,7 @@ cylindrical shape tool, as shown in the following figure:
    pyvista.global_theme.background = 'white'
    pyvista.global_theme.window_size = [600, 400]
    pyvista.global_theme.axes.show = True
-   pyvista.global_theme.antialiasing = True
+   pyvista.global_theme.anti_aliasing = "fxaa"
    pyvista.global_theme.show_scalar_bar = True
    mytheme = pyvista.global_theme
 

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 renamed to requirements/requirements_doc.txt

@@ -8,11 +8,11 @@ matplotlib==3.5.2
 numpydoc==1.3.1
 pandas==1.4.2
 plotly==5.8.0
-pyansys_sphinx_theme==0.3.1
+ansys-sphinx-theme==0.8.0
 pypandoc==1.8.1
 pytest-sphinx==0.4.0
 pythreejs==2.3.0
-https://github.com/pyvista/pyvista/archive/main.zip  # need latest
+# https://github.com/pyvista/pyvista/archive/main.zip  # need latest
 sphinx-autobuild==2021.3.14
 sphinx-autodoc-typehints==1.18.1
 sphinx-copybutton==0.5.0