Implementing multi-versioning

Author: RobPasMue

.github/workflows/ci_cd.yml

@@ -13,6 +13,8 @@ env:
   PACKAGE_NAME: 'ansys-geometry-core'
   # TODO : PIP_EXTRA_INDEX_URL should be deleted once the private dependencies are removed
   PIP_EXTRA_INDEX_URL: 'https://${{ secrets.PYANSYS_PYPI_PRIVATE_PAT }}@pkgs.dev.azure.com/pyansys/_packaging/pyansys/pypi/simple/'
+  PACKAGE_NAMESPACE: 'ansys.geometry.core'
+  DOCUMENTATION_CNAME: 'geometry.docs.pyansys.com'
   ANSRV_GEO_IMAGE: ghcr.io/pyansys/pygeometry:latest
   ANSRV_GEO_PORT: 700
   GEO_CONT_NAME: ans_geo
@@ -212,14 +214,14 @@ jobs:
       - name: Upload integration test logs
         uses: actions/upload-artifact@v3
         with:
-          name: Integration-Test-Logs
+          name: integration-test-logs
           path: tests/integration/logs
           retention-days: 7  
 
       - name: Upload Coverage Results
         uses: actions/upload-artifact@v3
         with:
-          name: HTML-Coverage
+          name: coverage-html
           path: .cov/html
           retention-days: 7
 
@@ -277,19 +279,37 @@ jobs:
           docker run --detach --name $env:GEO_CONT_NAME -p $env:ANSRV_GEO_PORT_MAP $env:ANSRV_GEO_IMAGE
           python -c "from ansys.geometry.core.connection.validate import validate; validate()"
 
-      - name: Build the documentation
+      - name: Build the documentation (HTML)
         run: |
           .\.venv\Scripts\Activate.ps1
           cd doc
           .\make.bat html
 
+      - name: Build the documentation (PDF)
+        # run: |
+        #   .\.venv\Scripts\Activate.ps1
+        #   cd doc
+        #   .\make.bat pdf
+        run: |
+          cd doc/_build
+          mkdir latex
+          cd latex
+          echo "" > dummy_docs.pdf
+
       - name: Upload HTML documentation
         uses: actions/upload-artifact@v3
         with:
-          name: HTML-Documentation
+          name: documentation-html
           path: doc/_build/html
           retention-days: 7
 
+      - name: Upload PDF documentation
+        uses: actions/upload-artifact@v3
+        with:
+          name: documentation-pdf
+          path: doc/_build/latex/*.pdf
+          retention-days: 7
+
       - name: Stop the geometry service
         if: always()
         run: |
@@ -378,44 +398,27 @@ jobs:
             ./**/*.tar.gz
             ./**/*.zip
 
-  upload_docs_release:
-    name: Upload documentation
-    if: (github.event_name == 'push' && contains(github.ref, 'refs/tags')) || (github.ref == 'refs/heads/main')
+  upload_docs_dev:
+    name: Upload dev documentation
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     needs: [package]
     steps:
-      - uses: actions/checkout@v3
-
-      - uses: actions/download-artifact@v3
-        with:
-          name: HTML-Documentation
-          path: HTML-Documentation
-
-      - name: Get Bot Application Token
-        id: get_workflow_token
-        uses: peter-murray/workflow-application-token-action@v2
+      - name: Deploy the latest documentation
+        uses: pyansys/actions/doc-deploy-dev@v1
         with:
-          application_id: ${{ secrets.BOT_APPLICATION_ID }}
-          application_private_key: ${{ secrets.BOT_APPLICATION_PRIVATE_KEY }}
+          cname: ${{ env.DOCUMENTATION_CNAME }}
+          token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Deploy documentation to pygeometry-dev-docs repository
-        if: github.ref == 'refs/heads/main'
-        uses: JamesIves/github-pages-deploy-action@v4.4.1
-        with:
-          repository-name: pyansys/pygeometry-dev-docs
-          token: ${{ steps.get_workflow_token.outputs.token }}
-          branch: gh-pages
-          folder: HTML-Documentation
-          clean: true
-          single-commit: true
-
-      - name: Deploy documentation to pygeometry-docs repository
-        if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
-        uses: JamesIves/github-pages-deploy-action@v4.4.1
+  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@v1
         with:
-          repository-name: pyansys/pygeometry-docs
-          token: ${{ steps.get_workflow_token.outputs.token }}
-          branch: gh-pages
-          folder: HTML-Documentation
-          clean: true
-          single-commit: true
+          cname: ${{ env.DOCUMENTATION_CNAME }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          python-version: ${{ env.MAIN_PYTHON_VERSION }}

doc/make.bat

@@ -12,6 +12,7 @@ set BUILDDIR=_build
 
 if "%1" == "" goto help
 if "%1" == "clean" goto clean
+if "%1" == "pdf" goto pdf
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -37,5 +38,10 @@ goto end
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
+:pdf
+%SPHINXBUILD% -M lulatex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+call %BUILDDIR%/latex/make.bat
+goto end
+
 :end
 popd

doc/source/conf.py

@@ -1,13 +1,29 @@
 """Sphinx documentation configuration file."""
 from datetime import datetime
+import os
 
 from ansys_sphinx_theme import ansys_favicon, pyansys_logo_black
+from sphinx.builders.latex import LaTeXBuilder
+
+from ansys.geometry.core import __version__
+
+LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
+
+
+def get_version_match(semver):
+    """Evaluate the version match for the multi-documentation."""
+    if semver.endswith("dev0"):
+        return "dev"
+    major, minor, _ = semver.split(".")
+    return ".".join([major, minor])
+
 
 # Project information
 project = "ansys-geometry-core"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
 author = "ANSYS, Inc."
 release = version = "0.1.0"
+cname = os.getenv("DOCUMENTATION_CNAME", default="nocname.com")
 
 # Select desired logo, theme, and declare the html title
 html_logo = pyansys_logo_black
@@ -17,6 +33,11 @@
 
 # specify the location of your github repo
 html_theme_options = {
+    "switcher": {
+        "json_url": f"https://{cname}/release/versions.json",
+        "version_match": get_version_match(__version__),
+    },
+    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
     "github_url": "https://github.com/pyansys/pygeometry",
     "show_prev_next": False,
     "show_breadcrumbs": True,