Update sphinx version, update actions and release docs (#812)

* Update actions, sphinx version and build docs for every PR
* Add separate action for testing docs
* Fix Release documentation
* Fix typo in docs workflow

Co-authored-by: Patricia Grubel <pagrubel@lanl.gov>

.github/workflows/docs.yml

@@ -1,44 +1,18 @@
-# Based on https://github.com/actions/starter-workflows/blob/main/pages/static.yml
-name: Publish docs
+name: Build Docs
 
 on:
+  workflow_dispatch: {}
   push:
-    branches: [main]
-
-# Needed for publishing to Github Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: "pages"
-  cancel-in-progress: true
+    branches: [main, develop]
+  pull_request:
+    types: [opened, synchronize, edited]
+    branches: [main, develop]
 
 jobs:
-  publish:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+  docs:
+    name: Build Docs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - name: BEE Install
-        run: |
-          sudo apt-get update
-          sudo apt-get install python3 python3-venv curl build-essential \
-            zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libsqlite3-dev \
-            libreadline-dev libffi-dev libbz2-dev libyaml-dev
-          curl -sSL https://install.python-poetry.org | python3 -
-          poetry update
-          poetry install
-      - name: Build Docs
-        run: |
-          poetry run make -C docs/sphinx html
-      - name: Upload
-        uses: actions/upload-pages-artifact@v1
-        with:
-          path: docs/sphinx/_build/html
-      - name: Publish
-        id: deployment
-        uses: actions/deploy-pages@v1
+      - uses: actions/checkout@v4
+      - name: Install BEE and Build Docs
+        run: ./ci/docs.sh

.github/workflows/integration.yml

@@ -25,7 +25,7 @@ jobs:
     # available on 20.04
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install and Configure
         run: |
           . ./ci/env.sh

.github/workflows/publish-docs.yml

@@ -0,0 +1,35 @@
+# Based on https://github.com/actions/starter-workflows/blob/main/pages/static.yml
+name: Publish docs
+
+on:
+  push:
+    branches: [main]
+
+# Needed for publishing to Github Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: BEE Install and Build Docs
+        run: |
+          ./ci/docs.sh
+      - name: Upload
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: docs/sphinx/_build/html
+      - name: Publish
+        id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/pylama.yml

@@ -15,7 +15,7 @@ jobs:
     name: PyLama Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Lint
         run: |
           pip install pylama==8.4.1 pyflakes==3.0.1 pylint==2.15.9 pydocstyle==6.1.1 2>&1 >/dev/null

.github/workflows/unit-tests.yml

@@ -23,7 +23,7 @@ jobs:
     # available on 20.04
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install and Configure
         run: |
           . ./ci/env.sh

RELEASE.rst

@@ -18,9 +18,14 @@ Verify all current changes in develop run correctly on nightly tests.
 5. Once merged, on github web interface create a release and tag based on main branch
    that matches the version in pyproject.toml
 6. Follow step 2 but uncheck Allow specified actors to bypass and don't forget save
-7. Finally, on the main branch, first run a ``poetry build`` and then a
-   ``poetry publish``. The second command will ask for a username and password (You may need to add the --username --password options to ``poetry build``)
-   for PyPI.
+7. Log into your PYPI account and get a token for hpc-beeflow.
+8. Finally, on the command line: checkout the main branch and make sure you pull the latest verison
+
+   Then publish by:
+       ``poetry build``
+
+       ``poetry publish -u __token__ -p pypi-<long-token>``
+
 
 Check the documentation at: `https://lanl.github.io/BEE/ <https://lanl.github.io/BEE/>`_ 
 Also upgrade the pip version in your python or anaconda environment and check the version:

ci/docs.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Install BEE and build the docs in CI.
+sudo apt-get update
+sudo apt-get install python3 python3-venv curl build-essential \
+    zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libsqlite3-dev \
+    libreadline-dev libffi-dev libbz2-dev libyaml-dev
+curl -sSL https://install.python-poetry.org | python3 -
+poetry update
+poetry install
+poetry run make -C docs/sphinx html

pyproject.toml

@@ -90,7 +90,7 @@ pylint = "2.15.9"
 pytest = "7.2.0"
 pytest-mock = "3.3.1"
 # This is commented out until we can figure out why it's causing `poetry update` to loop forever
-sphinx = "^2.1"
+sphinx = "^6"
 sphinx-rtd-theme = "^1.0"
 cwltool = "^3.0.20200324120055"