Merge pull request #8 from Staffbase/techdocs-additional-plugins

✨ Support for additional plugins / skip-publish

Author: axdotl

README.md

@@ -13,6 +13,8 @@ The action facilitated [TechDocs CLI](https://backstage.io/docs/features/techdoc
 
 ## Usage
 
+### Minimal Example
+
 The following shows a minimal example of building and publishing TechDocs to AWS S3.
 
 ```yaml
@@ -25,6 +27,7 @@ on:
     paths:
       - "docs/**"
       - "mkdocs.yml"
+      - ".github/workflows/techdocs.yml"
 
 jobs:
   publish-techdocs-site:
@@ -41,6 +44,33 @@ jobs:
           aws-secret-access-key: ${{ secrets.TECHDOCS_AWS_SECRET_ACCESS_KEY }}
 ```
 
+### Advanced Example
+
+The following will skip the publish step (e.g. to verify site generation in a pull request) and installs additional plugins:
+
+```yaml
+name: Publish TechDocs Site
+
+on:
+  push:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/techdocs.yml"
+
+jobs:
+  publish-techdocs-site:
+    name: Publish TechDocs Site
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Setup Node
+        uses: Staffbase/backstage-techdocs-action@v1
+        with:
+          entity-name: 'pizza-service'
+          additional-plugins: 'mkdocs-minify-plugin\>=0.3 mkdocs-awesome-pages-plugin==2.8.0 mdx_include==1.4.2'
+          skip-publish: 'true'
+```
+
 ## Configuration
 
 | Name                    | Description                                                                        | Required | Default        |
@@ -55,6 +85,8 @@ jobs:
 | `aws-secret-access-key` | **Required if `publisher-type: awsS3`** - AWS Secret Access Key                    | `false`  |                |
 | `azure-account-name`    | **Required if `publisher-type: azureBlobStorage`** - Azure Account Name            | `false`  |                |
 | `azure-account-key`     | **Required if `publisher-type: azureBlobStorage`** - Azure Account Key             | `false`  |                |
+| `additional-plugins`    | Space separated list of additional python plugins (Bash quoting for special chars) | `false`  |                |
+| `skip-publish`          | Indicates whether publish step should be skipped                                   | `false`  | `false`        |
 
 ## Contributing
 

action.yml

@@ -36,12 +36,19 @@ inputs:
   azure-account-key:
     description: 'Azure Account Name'
     required: false
+  additional-plugins:
+    description: 'List of additional python plugins to use for site creation'
+    required: false
+  skip-publish:
+    description: 'Indicates whether publish step should be skipped'
+    required: false
+    default: 'false'
 
 runs:
   using: "composite"
   steps:
     - name: Setup Node
-      uses: actions/setup-node@v3.4.1
+      uses: actions/setup-node@v3
 
     - name: Setup Python
       uses: actions/setup-python@v4
@@ -52,14 +59,23 @@ runs:
 
     - name: Install mkdocs and mkdocs plugins
       shell: bash
-      run: python -m pip install mkdocs-techdocs-core==0.*
+      run: python -m pip install mkdocs-techdocs-core==1.*
+
+    - name: Install additional plugins
+      if: inputs.additional-plugins != ''
+      shell: bash
+      run: |
+        for p in ${{ inputs.additional-plugins }}
+        do
+          python -m pip install $p
+        done
 
     - name: Generate docs site
       shell: bash
       run: techdocs-cli generate --no-docker --verbose
 
     - name: Publish TechDocs site to AWS S3
-      if: inputs.publisher-type == 'awsS3' && inputs.aws-access-key-id != '' && inputs.aws-secret-access-key != '' && inputs.aws-region != ''
+      if: inputs.skip-publish == 'false' && inputs.publisher-type == 'awsS3' && inputs.aws-access-key-id != '' && inputs.aws-secret-access-key != '' && inputs.aws-region != ''
       shell: bash
       env:
         AWS_ACCESS_KEY_ID: ${{ inputs.aws-access-key-id }}
@@ -71,7 +87,7 @@ runs:
         --entity ${{ inputs.entity-namespace }}/${{ inputs.entity-kind }}/${{ inputs.entity-name }}
 
     - name: Publish TechDocs site to Azure Blob
-      if: inputs.publisher-type == 'azureBlobStorage' && inputs.azure-account-name != '' && inputs.azure-account-key != ''
+      if: inputs.skip-publish == 'false' && inputs.publisher-type == 'azureBlobStorage' && inputs.azure-account-name != '' && inputs.azure-account-key != ''
       shell: bash
       run: |
         techdocs-cli publish --publisher-type ${{ inputs.publisher-type }} \

catalog-info.yaml

@@ -10,4 +10,4 @@ metadata:
     - backstage
 spec:
   type: other
-  lifecycle: experimental
+  lifecycle: production