[!] transform Sphinx manual to mkdocs-material

Author: pashagolub

.github/workflows/build.yml

@@ -1,6 +1,9 @@
 name: Go Build & Test
 on:
   pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
   workflow_dispatch:
 
 concurrency:

.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

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).

docs/api.rst

@@ -0,0 +1,86 @@
+# Getting started
+
+A variety of examples can be found in the [samples](samples.md). If you want to migrate from a different scheduler, you can use scripts from [migration](migration.md) chapter.
+
+## Add simple job
+
+In a real world usually it's enough to use simple jobs. Under this term we understand:
+
+* job is a chain with only one **task** (step) in it;
+* it doesn't use complicated logic, but rather simple **command**;
+* it doesn't require complex transaction handling, since one task is implicitely executed as a single transaction.
+
+For such a group of chains we've introduced a special function `timetable.add_job()`.
+
+### Function: `timetable.add_job()`
+
+Creates a simple one-task chain
+
+**Returns:** `BIGINT`
+
+#### Parameters
+
+| Parameter | Type | Description | Default |
+|-----------|------|-------------|---------|
+| `job_name` | `text` | The unique name of the **chain** and **command** | Required |
+| `job_schedule` | `timetable.cron` | Time schedule in сron syntax at Postgres server time zone | Required |
+| `job_command` | `text` | The SQL which will be executed | Required |
+| `job_parameters` | `jsonb` | Arguments for the chain **command** | `NULL` |
+| `job_kind` | `timetable.command_kind` | Kind of the command: *SQL*, *PROGRAM* or *BUILTIN* | `SQL` |
+| `job_client_name` | `text` | Specifies which client should execute the chain. Set this to `NULL` to allow any client | `NULL` |
+| `job_max_instances` | `integer` | The amount of instances that this chain may have running at the same time | `NULL` |
+| `job_live` | `boolean` | Control if the chain may be executed once it reaches its schedule | `TRUE` |
+| `job_self_destruct` | `boolean` | Self destruct the chain after execution | `FALSE` |
+| `job_ignore_errors` | `boolean` | Ignore error during execution | `TRUE` |
+| `job_exclusive` | `boolean` | Execute the chain in the exclusive mode | `FALSE` |
+
+**Returns:** the ID of the created chain
+
+## Examples
+
+1. Run `public.my_func()` at 00:05 every day in August Postgres server time zone:
+
+    ```sql
+    SELECT timetable.add_job('execute-func', '5 0 * 8 *', 'SELECT public.my_func()');
+    ```
+
+2. Run `VACUUM` at minute 23 past every 2nd hour from 0 through 20 every day Postgres server time zone:
+
+    ```sql
+    SELECT timetable.add_job('run-vacuum', '23 0-20/2 * * *', 'VACUUM');
+    ```
+
+3. Refresh materialized view every 2 hours:
+
+    ```sql
+    SELECT timetable.add_job('refresh-matview', '@every 2 hours', 'REFRESH MATERIALIZED VIEW public.mat_view');
+    ```
+
+4. Clear log table after **pg_timetable** restart:
+
+    ```sql
+    SELECT timetable.add_job('clear-log', '@reboot', 'TRUNCATE timetable.log');
+    ```
+
+5. Reindex at midnight Postgres server time zone on Sundays with [reindexdb](https://www.postgresql.org/docs/current/app-reindexdb.html) utility:
+
+    - using default database under default user (no command line arguments)
+  
+        ```sql
+        SELECT timetable.add_job('reindex', '0 0 * * 7', 'reindexdb', job_kind := 'PROGRAM');
+        ```
+    
+    - specifying target database and tables, and be verbose
+
+        ```sql
+        SELECT timetable.add_job('reindex', '0 0 * * 7', 'reindexdb', 
+            '["--table=foo", "--dbname=postgres", "--verbose"]'::jsonb, 'PROGRAM');
+        ```
+
+    - passing password using environment variable through `bash` shell
+
+        ```sql
+        SELECT timetable.add_job('reindex', '0 0 * * 7', 'bash', 
+            '["-c", "PGPASSWORD=5m3R7K4754p4m reindexdb -U postgres -h 192.168.0.221 -v"]'::jsonb, 
+            'PROGRAM');
+        ```