DOC: implement multi-doc in v0.61 (#1677)

* Adapt to multidoc for v0.61

* Adapt precommit for the patch for multidoc for v0.61

* Resolve style error

* rename reqirement.doc in ci/cd

* Modify make file

* Modify deploy actions

* Modify theme name

* FIX: output doc/_build dir

* CI: deploy only stable

Co-authored-by: Jorge Martinez Garrido <[email protected]>

Author: Revathyvenugopal162

.github/workflows/ci.yml

@@ -26,6 +26,11 @@ env:
   RESET_DOC_BUILD_CACHE: 0
   RESET_AUTOSUMMARY_CACHE: 0
   PACKAGE_NAME: PyMAPDL
+  DOCUMENTATION_CNAME: 'mapdl.docs.pyansys.com'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
 
@@ -136,7 +141,7 @@ jobs:
         uses: actions/cache@v2
         with:
           path: ~/.cache/pip
-          key: Python-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('setup.py') }}-${{ hashFiles('requirements/requirements_docs*.txt') }}
+          key: Python-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('setup.py') }}-${{ hashFiles('requirements/requirements_doc*.txt') }}
           restore-keys: |
             Python-${{ runner.os }}-${{ matrix.python-version }}
 
@@ -177,7 +182,7 @@ jobs:
       - name: Cache docs build directory
         uses: actions/cache@v2
         with:
-          path: doc/build
+          path: doc/_build
           key: doc-build-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }}
           restore-keys: |
             doc-build-${{ steps.version.outputs.PYMAPDL_VERSION }}
@@ -192,34 +197,24 @@ 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
+          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
+          path: doc/_build/html/PyMAPDL_documentation.zip
           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
@@ -228,7 +223,7 @@ jobs:
         uses: actions/upload-artifact@v2
         with:
           name: PDF-Documentation
-          path: doc/build/latex/pymapdl*.pdf
+          path: doc/_build/latex/pymapdl*.pdf
           retention-days: 7
 
   build_test:
@@ -349,3 +344,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.9'
+  

.pre-commit-config.yaml

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

doc/Makefile

@@ -1,43 +1,34 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
 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:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
 .PHONY: help Makefile
-
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-
 # customized clean due to examples gallery
 clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf source/examples
 	find . -type d -name "_autosummary" -exec rm -rf {} +
-
 # customized clean due to examples gallery
 clean-except-examples:
 	rm -rf $(BUILDDIR)/*
 	rm -rf images/auto-generated
 	find . -type d -name "_autosummary" -exec rm -rf {} +
-
 # customized to build the pdf rather than using latexpdf due to various issues
 # with our docs like GIFs being written as PNG.
 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 +38,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 $(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

@@ -1,14 +1,12 @@
 @ECHO OFF
-
 pushd %~dp0
-
 REM Command file for Sphinx documentation
-
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
-set BUILDDIR=build
+set BUILDDIR=_build
+
 
 if "%1" == "" goto help
 
@@ -24,12 +22,10 @@ if errorlevel 9009 (
 	echo.http://sphinx-doc.org/
 	exit /b 1
 )
-
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
 :end
-popd
+popd

doc/source/conf.py

@@ -3,11 +3,12 @@
 import os
 import warnings
 
+from ansys_sphinx_theme import 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
 
+cname = os.getenv("DOCUMENTATION_CNAME", "nocname.com")
 from ansys.mapdl.core import __version__
 
 # Manage errors
@@ -167,7 +168,7 @@
 
 # -- 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",
@@ -176,6 +177,11 @@
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
     ],
+    "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 renamed to requirements/requirements_doc.txt

@@ -8,7 +8,7 @@ matplotlib==3.5.1
 numpydoc==1.2
 pandas==1.4.1
 plotly==5.6.0
-pyansys_sphinx_theme==0.2.3
+ansys_sphinx_theme==0.8.0
 pypandoc==1.7.4
 pytest-sphinx==0.3.1
 pythreejs==2.3.0