compatible: Add sync_docs.yaml (#220)

The sync_docs workflow that originally called the discourse-gatekeeper
action was replaced by a small custom script.

## Reasoning
- Greatly simplifies troubleshooting and maintenance of our
documentation sync workflow.
- Removes two important limitations:
1. We can give navigation groups their own landing page (e.g. A level 1
`[Tutorial]()` row can now have a landing page `[Tutorial](/t/123)`
while remaining an expandable group). This functionality is part of
Canonical's documentation requirements (see [Diataxis docs regarding
navigation](https://diataxis.fr/complex-hierarchies/#structure-of-documentation-content)).
2. We can nest items more than 1 level away from each other (e.g. A
level 3 page can be followed by a level 1 page)

---------

Co-authored-by: Carl Csaposs <carl.csaposs@canonical.com>

.github/workflows/sync_docs.md

@@ -0,0 +1,95 @@
+Workflow file: [sync_docs.yaml](sync_docs.yaml)
+
+## Usage
+Add `.yaml` file to `.github/workflows/`
+
+```yaml
+# Copyright 2024 Canonical Ltd.
+# See LICENSE file for licensing details.
+name: Sync Discourse docs
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '53 0 * * *'  # Daily at 00:53 UTC
+
+jobs:
+  sync-docs:
+    name: Sync docs from Discourse
+    uses: canonical/data-platform-workflows/.github/workflows/sync_docs.yaml@v0.0.0
+    with:
+      reviewers: canonical/data-platform-technical-authors,octocat
+    permissions:
+      contents: write  # Needed to push branch & tag
+      pull-requests: write  # Needed to create PR
+```
+
+## Behavior
+
+Downloads all Discourse topics in the charm's Charmhub documentation to `/docs/` directory in the charm's repository.
+
+>[!NOTE]
+> Any content in the `/docs/` directory that is not part of this workflow will get removed.
+
+The topics are determined by the navigation table in the charm's overview page - i.e. the page linked in the `metadata.yaml` `docs:` field. 
+
+When the workflow is triggered, it downloads all Discourse topics in their latest state and compares them to the `/docs/` directory in the default branch (e.g. `main`).
+* If the contents match, GitHub is up to date with Discourse. Nothing happens.
+* If the contents do not match, Discourse is ahead of GitHub. The workflow opens or updates a PR for the `sync-docs` branch with the diff between Discourse and GitHub.
+
+Each Discourse topic is downloaded to either: `/docs/`, `/docs/tutorial/`, `/docs/how-to/`, `/docs/reference/`, or `/docs/explanation/` depending on their slug prefix. Sub-categories will not create an additional directory.
+
+```
+# Example navtable:
+
+| Level |      Path      |          Navlink          |
+|-------|----------------|---------------------------|
+|   1   | t-landing      | [Tutorial](/t/123)        |
+|   2   | t-introduction | [Introduction](/t/124)    |
+|   1   | h-landing      | [How To]()                |
+|   2   | h-set-up       | [Set up](/t/125)          |
+|   3   | h-deploy-lxd   | [Deploy on LXD](/t/126)   |
+|   2   | h-monitoring   | [Monitoring]()            |
+|   3   | h-alert        | [Add alert rules](/t/127) |
+
+# Expected /docs output:
+
+/docs/overview.md
+/docs/tutorial/t-landing.md
+/docs/tutorial/t-introduction.md
+/docs/how-to/h-set-up.md
+/docs/how-to/h-deploy-lxd.md
+/docs/how-to/h-alert.md
+```
+
+## Documentation requirements
+
+**Requirement**: The overview topic must contain a navigation table with the columns "Level", "Path", and "Navlink"
+
+**Requirement**: The navigation table of the overview topic must be wrapped by the `[details]` HTML/markdown element as follows:
+
+```
+# Navigation
+
+[details=Navigation]
+
+<navigation table goes here>
+
+[/details]
+
+```
+
+> [!NOTE]  
+> Make sure to leave a white space before and after the `[details]` and `[/details]` lines. Otherwise, Discourse/Charmhub may not parse them correctly.
+
+**Requirement**: Links to topics in the `Navlink` column must be formatted as `[Text](/t/<topic_id>)`. 
+
+They **must not** be formatted as `[Text](/t/<some-additional-slug-text>/<topic_id>)`.
+
+### Examples
+The following documentation sets fulfill the above requirements and have been tested:
+* [PostgreSQL VM](https://discourse.charmhub.io/t/charmed-postgresql-documentation/9710)
+* [PostgreSQL K8s](https://discourse.charmhub.io/t/charmed-postgresql-k8s-documentation/9307)
+* [PgBouncer VM](https://discourse.charmhub.io/t/pgbouncer-documentation/12133)
+* [PgBouncer K8s](https://discourse.charmhub.io/t/pgbouncer-k8s-documentation/12132)
+* [MySQL Router K8s](https://discourse.charmhub.io/t/mysql-router-k8s-documentation/12130)

.github/workflows/sync_docs.yaml

@@ -0,0 +1,58 @@
+on:
+  workflow_call:
+    inputs:
+      reviewers:
+        description: Comma separated list of GitHub usernames to request to review pull request (e.g. "canonical/data-platform-engineers,octocat")
+        required: false
+        type: string
+
+jobs:
+  sync-docs:
+    name: Sync docs from Discourse
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+    - name: Get workflow version
+      id: workflow-version
+      uses: canonical/get-workflow-version-action@v1
+      with:
+        repository-name: canonical/data-platform-workflows
+        file-name: sync_docs.yaml
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+    - name: Install CLI
+      run: pipx install git+https://github.com/canonical/data-platform-workflows@'${{ steps.workflow-version.outputs.sha }}'#subdirectory=python/cli
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Update Discourse docs
+      run: sync-docs
+    - name: Push `sync-docs` branch & create pull request
+      run: |
+        git checkout -b sync-docs
+        git add docs/
+        # Check if changes staged
+        if git diff --cached --quiet
+        then
+          echo 'No changes to docs/ from default git branch'
+          # Delete branch on GitHub if it exists
+          # (GitHub will automatically close PR if it exists)
+          if git ls-remote --exit-code origin sync-docs
+          then
+            git push origin --delete sync-docs
+          fi
+          exit 0
+        fi
+        git config user.name "GitHub Actions"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git commit -m "Sync docs from Discourse"
+        git push origin sync-docs -f
+        # Create pull request
+        # Capture output in variable so that step fails if `gh pr list` exits with non-zero code
+        prs=$(gh pr list --head sync-docs --state open --json number)
+        if [[ $prs != "[]" ]]
+        then
+          echo Open pull request already exists
+          exit 0
+        fi
+        gh pr create --head sync-docs --title "Sync docs from Discourse" --body "Sync charm docs from https://discourse.charmhub.io" --reviewer '${{ inputs.reviewers }}'
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -12,7 +12,7 @@
 | [release_charm.yaml](.github/workflows/release_charm.md)                   | Release charm to Charmhub                                                  |
 | [update_bundle.yaml](.github/workflows/update_bundle.md)                   | Update charm revisions in bundle                                           |
 | [sync_issue_to_jira.yaml](.github/workflows/sync_issue_to_jira.md)         | Sync GitHub issues to Jira issues                                          |
-| [_sync_docs.yaml](.github/workflows/_sync_docs.md)                         | **Experimental** Sync Discourse documentation to GitHub                    |
+| [sync_docs.yaml](.github/workflows/sync_docs.md)                           | Sync Discourse documentation to GitHub                                     |
 
 ### Version
 Recommendation: pin the latest version (e.g. `v1.0.0`) and use [Renovate](https://docs.renovatebot.com/) to stay up-to-date.
@@ -72,4 +72,4 @@ Workflows that begin with one underscore (e.g. `_foo.yaml`) are internal and are
 Workflows that begin with two underscores (e.g. `__foo.yaml`) are for this repository only. They may only be (triggered by an event on this repository or) called by workflows in this repository that begin with two underscores.
 
 ## Contributing
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md)