pdoc API documentation build and publish CI (#18)

Hi. Here’s one more Python example. It makes use of [pdoc](https://pdoc.dev) in order to generate the API documentation for python modules. The docs are then pushed on a pages branch and normally served by codeberg pages.

Co-authored-by: mononym <mononym@riseup.net>
Reviewed-on: https://codeberg.org/Codeberg-CI/examples/pulls/18
Reviewed-by: Patrick Schratz <pat-s@noreply.codeberg.org>
Co-authored-by: mononym <mononym@noreply.codeberg.org>
Co-committed-by: mononym <mononym@noreply.codeberg.org>

Python/pdoc.yml

@@ -0,0 +1,48 @@
+# build pdoc documentation into /public
+# push content of /public to EXISTING pages branch
+
+when:
+  branch: main
+  event: push
+
+clone:
+  git:
+    image: woodpeckerci/plugin-git
+    settings:
+      recursive: true
+
+steps:
+  build:
+    image: python:3.9-buster
+    commands:
+      - python -m venv venv
+      - /bin/bash -c "source venv/bin/activate"
+      - python -m pip install --upgrade pip
+      # install requirements from your source code (needed by pdoc)
+      - python -m pip install --upgrade -r requirements.txt
+      - python -m pip install pdoc
+      # locate the part of your code to be documented
+      - pdoc <my_python_module_or_file> -o public # test locally
+
+  publish:
+    image: bitnami/git:2
+    secrets: [ cbtoken ]
+    commands:
+      # config git to commit and push changes
+      - git config --global --add safe.directory $CI_WORKSPACE/public
+      - git config --global user.email "woodpecker-bot@no-reply.eu"
+      - git config --global user.name "woodpecker-bot"
+      - git config --global init.defaultBranch pages
+      # clone the existing pages branch which will be updated with new pdoc build
+      - git clone -b pages https://$CBTOKEN@codeberg.org/<user_name>/<repo_name>.git build_pdocs
+      # purge existing docs
+      - rm -rf build_pdocs/*
+      # add new docs
+      - cp -a public/* build_pdocs/
+      # commit and push to pages branch
+      - cd build_pdocs/
+      - git remote set-url origin https://$CBTOKEN@codeberg.org/<user_name>/<repo_name>.git
+      - git add --all
+      # exclude current push from CI pipeline triggering
+      - git commit -m "deploy $CI_COMMIT_SHA [CI SKIP]"
+      - git push -u origin pages

README.md

@@ -18,6 +18,7 @@ Pull requests are accepted/welcome.
 | [Docker/buildx.yml](Docker/buildx.yml)               | Dockerfile  | [buildx][2]         | Build and publish Docker images for multiple architectures on codeberg                                                                                                   |
 | [Python/.woodpecker.yml](Python)                     | Python      | Python venv         | Standard CI pipeline to test Python packages code on multiple Python distributions. For details check [serial-sphinx](https://codeberg.org/sail.black/serial-sphinx.git) |
 | [Python/mkdocs.yml](Python/mkdocs.yml)               | Markdown    | MkDocs              | Static Site Generator mkdocs example                                                                                                                                     |
+| [Python/pdoc.yml](Python/pdoc.yml)                   | Python      | Python venv         | Build API documentation with pdoc & publish files on a pages branch                                                                                                      |
 | [Rust/.woodpecker.yml](Rust)                         | Rust        | cargo               | Simple CI pipeline to run cargo commands                                                                                                                                 |
 | [StandardML/sml.yml](StandardML)                     | Standard ML | sml                 | Simple CI pipeline to run SML files                                                                                                                                      |
 | [tectonic/.woodpecker.yml](tectonic/.woodpecker.yml) | LaTeX       | Tectonic            | Builds a TeX file and pushes the resulting PDF file to a given repository.                                                                                               |