[!] transform Sphinx manual to mkdocs-material (#711)

* add build-docs GHA job
* bump go and python version
* use cache for pip
* fix links
* fix readme badges

Author: pashagolub

.github/workflows/build.yml

@@ -1,6 +1,16 @@
-name: Go Build & Test
+name: Build and Test
+
+permissions:
+  contents: write
+  packages: write
+  pages: write
+
 on:
+  push:
+    branches:
+      - master
   pull_request:
+    paths-ignore: ['docs/**', 'mkdocs.yml']
   workflow_dispatch:
 
 concurrency:
@@ -92,8 +102,6 @@ jobs:
     - name: Test
       run: go test -v -p 1 -parallel 1 -failfast ./...
 
-
-
   test-postgresql-ubuntu:
     if: true # false to skip job during debug
     name: Test and Build on Ubuntu
@@ -145,3 +153,48 @@ jobs:
       with:
         version: latest
         args: release --snapshot --skip=publish --clean
+
+  build-docs:
+    if: true # false to skip job during debug
+    needs: [test-postgresql-ubuntu, test-postgresql-windows, test-postgresql-macos]
+    name: Build Docs
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Check out code
+      uses: actions/checkout@v5
+
+    - name: Configure Git
+      run: |
+        git config user.name "${GITHUB_ACTOR}"
+        git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+
+    - name: Set up Golang
+      uses: actions/setup-go@v6
+      with:
+        go-version: '1.25'      
+    
+    - name: Set up gopages
+      run: go install github.com/johnstarich/go/[email protected]
+    
+    - name: Build Developer Docs
+      run: gopages -out "docs/godoc" -base "/pg_timetable/devel/godoc" -internal
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: 3.13
+        cache: 'pip'
+        cache-dependency-path: '**/requirements-doc.txt'
+
+    - name: Install dependencies
+      run: pip install -r docs/requirements-doc.txt
+
+    - name: Check if we should push to gh-pages
+      # if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+      run: |
+        git fetch origin gh-pages --depth=1
+        echo "push_opt=--push" >> $GITHUB_ENV 
+
+    - name: Build mkdocs
+      run: mike deploy ${{ env.push_opt }} devel

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Deploy MkDocs Documentation
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs-material
+          pip install mkdocstrings[python]
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Build with MkDocs
+        run: mkdocs build --config-file mkdocs.yml
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -1,7 +1,7 @@
+[![Documentation](https://img.shields.io/badge/Documentation-pg__timetable-brightgreen)](https://cybertec-postgresql.github.io/pg_timetable/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-![Build & Test](https://github.com/cybertec-postgresql/pg_timetable/workflows/Go%20Build%20&%20Test/badge.svg)
+![Build & Test](https://github.com/cybertec-postgresql/pg_timetable/workflows/Build%20and%20Test/badge.svg)
 [![Coverage Status](https://coveralls.io/repos/github/cybertec-postgresql/pg_timetable/badge.svg?branch=master&service=github)](https://coveralls.io/github/cybertec-postgresql/pg_timetable?branch=master)
-[![Documentation Status](https://readthedocs.org/projects/pg-timetable/badge/?version=master)](https://pg-timetable.readthedocs.io/en/master/?badge=master)
 [![Release](https://img.shields.io/github/v/release/cybertec-postgresql/pg_timetable?include_prereleases)](https://github.com/cybertec-postgresql/pg_timetable/releases)
 [![Github All Releases](https://img.shields.io/github/downloads/cybertec-postgresql/pg_timetable/total?style=flat-square)](https://github.com/cybertec-postgresql/pg_timetable/releases)
 [![Docker Pulls](https://img.shields.io/docker/pulls/cybertecpostgresql/pg_timetable)](https://hub.docker.com/r/cybertecpostgresql/pg_timetable)

docs/README.rst

@@ -0,0 +1,26 @@
+# REST API
+
+**pg_timetable** has a rich REST API, which can be used by external tools in order to perform start/stop/reinitialize/restarts/reloads, 
+by any kind of tools to perform HTTP health checks, and of course, could also be used for monitoring.
+
+Below you will find the list of **pg_timetable** REST API endpoints.
+
+## Health check endpoints
+
+### `GET /liveness`
+Always returns HTTP status code `200`, indicating that **pg_timetable** is running.
+
+### `GET /readiness`
+Returns HTTP status code `200` when the **pg_timetable** is running, and the scheduler is in the main loop processing chains. 
+If the scheduler connects to the database, creates the database schema, or upgrades it, it will return the HTTP status code `503`.
+
+## Chain management endpoints
+
+### `GET /startchain?id=<chain-id>`
+Returns HTTP status code `200` if the chain with the given id can be added to the worker queue. It doesn't, however, mean the chain execution starts immediately. It is up to the worker to perform load and other checks before starting the chain.
+In the case of an error, the HTTP status code `400` followed by an error message returned.
+
+### `GET /stopchain?id=<chain-id>`
+Returns HTTP status code `200` if the chain with the given id is working at the moment and can be stopped. If the chain is running the  
+cancel signal would be sent immediately.
+In the case of an error, the HTTP status code `400` followed by an error message returned.

docs/api.md

@@ -0,0 +1,28 @@
+# Project background
+
+The pg_timetable project got started back in 2019 for internal scheduling needs at Cybertec.
+
+For more background on the project motivations and design goals see the original series of blogposts announcing the project
+and the following feature updates.
+
+Cybertec also provides commercial 9-to-5 and 24/7 support for pg_timetable.
+
+* [Project announcement](https://www.cybertec-postgresql.com/en/pg_timetable-advanced-postgresql-job-scheduling/)
+
+* [v2 released](https://www.cybertec-postgresql.com/en/pg_timetable-advanced-postgresql-cron-like-scheduler-released/)
+
+* [Start-up improvements](https://www.cybertec-postgresql.com/en/pg_timetable-start-up-improvements/)
+
+* [v3 released](https://www.cybertec-postgresql.com/en/pg_timetable-v3-is-out/)
+
+* [Exclusive jobs explained](https://www.cybertec-postgresql.com/en/postgresql-exclusive-cron-jobs-using-pg_timetable-scheduler/)
+
+* [Asynchronous chain execution](https://www.cybertec-postgresql.com/en/pg_timetable-asynchronous-chain-execution/)
+
+* [v4 released](https://www.cybertec-postgresql.com/en/pg_timetable_v4-is-out/)
+
+* [PostgreSQL schedulers: comparison table](https://www.cybertec-postgresql.com/en/postgresql-schedulers-comparison-table/)
+
+## Project feedback
+
+For feature requests or troubleshooting assistance please open an issue on project's [Github page](https://github.com/cybertec-postgresql/pg_timetable).