feat: enable multidocs (#278)

* feat: enable multidocs

* fix: rename requirements_doc file

* feat: enable PDF build

* feat: disable Python cache

* fiz: change build-dir

* feat: install pandoc

* fix: skip deps cache

Author: RobPasMue

.github/workflows/testing-and-deployment.yml

@@ -9,6 +9,7 @@ env:
   PYMAPDL_DB_PORT: 21001  # default won't work on GitHub runners
   PYMAPDL_START_INSTANCE: FALSE
   DOCKER_PACKAGE: ghcr.io/pyansys/pymapdl/mapdl
+  DOCUMENTATION_CNAME: reader.docs.pyansys.com
 
 on:
   pull_request:
@@ -24,55 +25,30 @@ concurrency:
 
 jobs:
   doc_build:
-    name: Build Documentation
+    name: Build documentation
     runs-on: ubuntu-latest
-
     steps:
-      - uses: actions/checkout@v3
-
-      - name: Setup Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.10"
-
       - name: Setup headless display
         uses: pyvista/setup-headless-display-action@v2
 
-      - name: Install ansys-mapdl-reader
-        run: |
-          pip install -e .
-          cd tests/
-          python -c "from ansys.mapdl import reader as pymapdl_reader; print(pymapdl_reader.Report())"
-
-      - name: Install OS packages
-        run: |
-          sudo apt-get update
-          sudo apt-get install zip pandoc -qy
-
-      - name: Build Documentation
-        run: |
-          pip install -r requirements/requirements_docs.txt --disable-pip-version-check
-          make -C doc html
-          cd doc/build/html/
-          zip -r ../../../${{ env.PACKAGE_NAME }}-HTML.zip ./*
-
-      - name: Upload
-        uses: actions/upload-artifact@v3
+      - name: Build project documentation
+        uses: ansys/actions/doc-build@v4
         with:
-          name: ${{ env.PACKAGE_NAME }}-Documentation
-          path: |
-            ${{ env.PACKAGE_NAME }}-HTML.zip
-            doc/build/latex/*.pdf
-          retention-days: 7
+          dependencies: 'pandoc'
+          skip-dependencies-cache: true
+          use-python-cache: false
+          python-version: "3.10"
 
-      - name: Deploy
-        uses: JamesIves/github-pages-deploy-action@v4
-        if: startsWith(github.ref, 'refs/tags/')
+  doc-deploy-dev:
+    name: Upload development documentation
+    runs-on: ubuntu-latest
+    needs: [doc_build]
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: ansys/actions/doc-deploy-dev@v4
         with:
+          cname: ${{ env.DOCUMENTATION_CNAME }}
           token: ${{ secrets.GITHUB_TOKEN }}
-          branch: gh-pages
-          folder: doc/build/html
-          clean: true
 
   build:
     name: Build and Test
@@ -262,6 +238,12 @@ jobs:
       - name: Display structure of downloaded files
         run: ls -R
 
+      - name: Compressing HTML documentation
+        uses: vimtor/[email protected]
+        with:
+          files: documentation-html
+          dest: documentation-html.zip
+
       - name: Upload to Public PyPi
         run: |
           pip install twine
@@ -279,3 +261,15 @@ jobs:
             ./**/*.whl
             ./**/*.zip
             ./**/*.pdf
+
+  doc-deploy-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: ansys/actions/doc-deploy-stable@v4
+        with:
+          cname: ${{ env.DOCUMENTATION_CNAME }}
+          token: ${{ secrets.GITHUB_TOKEN }}

doc/Makefile

@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -21,5 +21,11 @@ help:
 
 # customized clean due to examples gallery
 clean:
-	rm -rf build
+	rm -rf $(BUILDDIR)
 	rm -rf source/examples
+
+# Create PDF
+pdf:
+	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
+	(test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1

doc/source/conf.py

@@ -2,7 +2,7 @@
 import os
 import warnings
 
-from ansys_sphinx_theme import pyansys_logo_black
+from ansys_sphinx_theme import get_version_match, pyansys_logo_black
 import pyvista
 from sphinx_gallery.sorting import FileNameSortKey
 
@@ -141,13 +141,28 @@
 
 
 # -- Options for HTML output -------------------------------------------------
+cname = os.getenv("DOCUMENTATION_CNAME", default="nocname.com")
+switcher_version = get_version_match(version)
 html_short_title = html_title = "PyMAPDL - Legacy Reader"
 html_theme = "ansys_sphinx_theme"
 html_logo = pyansys_logo_black
+html_context = {
+    "github_user": "ansys",
+    "github_repo": "pymapdl-reader",
+    "github_version": "main",
+    "doc_path": "doc/source",
+}
 html_theme_options = {
-    "github_url": "https://github.com/pyansys/pymapdl-reader",
+    "switcher": {
+        "json_url": f"https://{cname}/versions.json",
+        "version_match": switcher_version,
+    },
+    "check_switcher": False,
+    "github_url": "https://github.com/ansys/pymapdl-reader",
     "show_prev_next": False,
     "show_breadcrumbs": True,
+    "collapse_navigation": True,
+    "use_edit_page_button": True,
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
     ],