ci: update input descriptions, change pypi_token input

.github/workflows/doxygen_build.yml

@@ -4,9 +4,14 @@ on:
   workflow_call:
     inputs:
       output_dir:
+        description: "Output directory for Doxygen to compile"
         required: true
         type: string
       cache_key:
+        description: |
+          The cache key to pass to mkdocs_build, e.g.: 
+          echo "cache_key=docs-build-$(date --utc '+%V')" >> $GITHUB_ENV
+          Then use, with: cache_key: ${{ env.cache_key }}
         required: false
         type: string
 

.github/workflows/mkdocs_build.yml

@@ -4,9 +4,14 @@ on:
   workflow_call:
     inputs:
       cache_path:
+        description: "The path from a previously cached job, e.g. `apidocs` from Doxygen."
         required: false
         type: string
       cache_key:
+        description: |
+          The cache key to receive from a previous job, e.g.: 
+          echo "cache_key=docs-build-$(date --utc '+%V')" >> $GITHUB_ENV
+          Then use, with: cache_key: ${{ env.cache_key }}
         required: false
         type: string
 

.github/workflows/pypi_publish.yml

@@ -3,14 +3,17 @@ name: Publish to PyPi.org
 on:
   workflow_call:
     inputs:
-      pypi_token:
+      token_secret_name:
+        description: "The name of the repository secret containing the PyPi token."
         required: true
         type: string
 
 jobs:
   publish_to_pypi:
     name: Publish to PyPi
     runs-on: ubuntu-latest
+    env:
+      PYPI_TOKEN: ${{ secrets[inputs.token_secret_name] }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -22,5 +25,5 @@ jobs:
       - name: Publish
         run: |
           pdm config repository.pypi.username "__token__"
-          pdm config repository.pypi.password "${{ inputs.pypi_token }}"
+          pdm config repository.pypi.password "$PYPI_TOKEN"
           pdm publish