Merge pull request #348 from jchanvfx/sphinx_docs_workflow

auto doc build action #347

Author: jchanvfx

.github/workflows/pypi_publish.yml

@@ -1,10 +1,11 @@
 # Workflow for publishing module package to https://pypi.org.
-name: PyPI Package Publish
+name: Publish PyPI Package
 
 on:
   # trigger this workflow when a release is published.
   release:
-    types: [published]
+    types:
+      - published
 
 jobs:
   publish:

.github/workflows/sphinx_doc_build.yml

@@ -0,0 +1,59 @@
+# Workflow for building the sphinx api documentation.
+name: Build API Documentation
+
+on:
+  # trigger this workflow when a release is published.
+  release:
+    types:
+      - published
+
+env:
+  # environment variables.
+  SOURCE_BRANCH: main
+  GH_PAGES_BRANCH: gh-pages
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE , so your workflow can access it.
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      # Install Graphviz required for the sphinx plugin.
+      - name: Set up Graphviz
+        uses: ts-graphviz/setup-graphviz@v1
+      # Install a version of python.
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+      # Install the python dependencies required for building.
+      - name: Install Dependencies
+        run: |
+            pip install -U sphinx
+            pip install sphinx-rtd-theme
+            pip install PySide2
+            pip install Qt.py
+      # Set the local git configs.
+      - name: Set Git Config
+        run: |
+            git config --local user.email "[email protected]"
+            git config --local user.name "Github Actions"
+      # Merge the "main" branch to the "gh-pages" branch.
+      - name: Update "gh-pages" branch
+        run: |
+            git checkout $GH_PAGES_BRANCH
+            git merge $SOURCE_BRANCH
+            git push origin $GH_PAGES_BRANCH
+      # Build the sphinx api documentation.
+      - name: Run Sphinx Build
+        run: sphinx-build -b html ./docs ./api -a -E
+      # Deploy the html updates to the "gh-pages" branch.
+      - name: Deploy HTML
+        run: |
+            git ls-files --others --exclude-standard
+            git add ./api
+            git commit -m "auto build docs"
+            git push origin $GH_PAGES_BRANCH

.gitignore

@@ -4,7 +4,6 @@ venv/*
 
 # sphinx documentation
 docs/_build/
-api/*
 
 # python stuff
 *.pyc

docs/conf.py

@@ -47,10 +47,10 @@
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.autosummary',
     'sphinx.ext.coverage',
+    'sphinx.ext.graphviz',
     'sphinx.ext.inheritance_diagram',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
-    'autodocsumm',
 ]
 
 intersphinx_mapping = {
@@ -105,7 +105,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.