add docs

Author: 3nids

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: "📚 Documentation Builder"
+
+on:
+  push:
+    branches:
+        - main
+        - docs
+    paths:
+      - .github/workflows/docs_builder.yml
+      - pgserviceparser/**/*.py
+      - docs/**/*
+      - requirements/documentation.txt
+    tags:
+      - "*"
+
+  pull_request:
+    branches:
+        - main
+    paths:
+      - .github/workflows/docs_builder.yml
+      - pgserviceparser/**/*.py
+      - docs/**/*
+      - requirements/documentation.txt
+
+# Allow one concurrent deployment
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Get source code
+      uses: actions/checkout@v4
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install pgserviceparser
+      run: python -m pip install -r docs/requirements.txt
+
+    - name: Build documentation
+      run: mkdocs build -f docs/mkdocs.yml
+
+    - uses: actions/upload-artifact@v4
+      if: ${{ github.event_name == 'pull_request' }}
+      with:
+        name: docs
+        path: docs/site
+        if-no-files-found: error
+
+    - name: Deploy to GitHub Pages
+      if: contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name)
+      working-directory: docs
+      run: mkdocs gh-deploy --force

README.md

@@ -30,7 +30,7 @@ Managing database migrations in a Version Control System (VCS) can be challengin
 
 ### Best Practices
 
-- **Separate Schemas**: Isolate data and business logic (e.g., views, triggers) into distinct schemas for easier upgrades.
+- **Separate Schemas**: Isolate data from business logic (e.g., views, triggers) into distinct schemas for easier upgrades.
 - **Read More**: Explore articles like [Get Your Database Under Version Control](https://blog.codinghorror.com/get-your-database-under-version-control/) for insights into database versioning.
 
 ### Learn More
@@ -42,34 +42,33 @@ Managing database migrations in a Version Control System (VCS) can be challengin
 PUM was developed to address challenges in the [TEKSI](https://github.com/TESKI) project, an open-source GIS for network management based on [QGIS](http://qgis.org/fr/site/).
 
 
+
+
 ## Command line
 
 ### pum
 
 The usage of the pum command is:
 ```commandline
-
 usage: pum [-h] [-v] [-c CONFIG_FILE]
-           {check,dump,restore,baseline,info,upgrade,test}
-           ...
+       {check,dump,restore,baseline,info,upgrade,test}
+       ...
 
 optional arguments:
-  -h, --help            show this help message and exit
-  -v, --version         print the version and exit
+  -h, --help            Show this help message and exit.
+  -v, --version         Print the version and exit.
   -c CONFIG_FILE, --config_file CONFIG_FILE
-                        set the config file
+            Specify the configuration file.
 
 commands:
-  valid pum commands
-
   {check,dump,restore,baseline,info,upgrade,test}
-    check               check the differences between two databases
-    dump                dump a Postgres database
-    restore             restore a Postgres database from a dump file
-    baseline            Create upgrade information table and set baseline
-    info                show info about upgrades
-    upgrade             upgrade db
-
+  check               Compare two databases and display differences.
+  dump                Create a backup of a PostgreSQL database.
+  restore             Restore a PostgreSQL database from a backup file.
+  baseline            Initialize upgrade information table and set baseline.
+  info                Display the status of applied or pending upgrades.
+  upgrade             Apply SQL delta files to upgrade the database.
+  test                Run tests to validate database migrations.
 ```
 
 Pum is using [postgres connection service file](https://www.postgresql.org/docs/current/static/libpq-pgservice.html) to define the database connection parameters.