Skip to content

Commit 4d85485

Browse files
ismailsimsekismailsimsek
committed
docs: set up mkdocs documentation and update README
1 parent 0abbc48 commit 4d85485

File tree

6 files changed

+181
-7
lines changed

6 files changed

+181
-7
lines changed

‎.github/workflows/deploy-documentation.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: deploy-mkdocs-documentation
2+
on:
3+
push:
4+
branches:
5+
- master
6+
- main
7+
permissions:
8+
contents: write
9+
jobs:
10+
deploy:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- name: Configure Git Credentials
15+
run: |
16+
git config user.name github-actions[bot]
17+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: 3.x
21+
- run: pip install mkdocs-material
22+
- run: mkdocs gh-deploy --force

‎README.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,22 @@
1-
[![License](http://img.shields.io/:license-apache%202.0-brightgreen.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
2-
![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)
3-
[![Create Pypi Release](https://github.com/memiiso/pyliquibase/actions/workflows/release.yml/badge.svg)](https://github.com/memiiso/pyliquibase/actions/workflows/release.yml)
41
# pyliquibase
52

63
A Python module to use [liquibase](http://www.liquibase.org/) in python, using the Java Native Interface (JNI).
74

8-
For further details on python-java integration [please see here](#python-java-integration)
5+
[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://memiiso.github.io/pyliquibase/)
6+
[![License](http://img.shields.io/:license-apache%202.0-brightgreen.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
7+
![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)
8+
[![Create Pypi Release](https://github.com/memiiso/pyliquibase/actions/workflows/release.yml/badge.svg)](https://github.com/memiiso/pyliquibase/actions/workflows/release.yml)
9+
10+
For full documentation, please visit [https://memiiso.github.io/pyliquibase/](https://memiiso.github.io/pyliquibase/)
911

1012
## Installation
11-
Python-Java integration requires a Java Development Kit (JDK). Ensure a JDK is installed on your operating system.
13+
Python-Java integration requires Java. Ensure Java is installed on your operating system.
1214

13-
install:
1415
```shell
1516
pip install pyliquibase
1617
```
1718

18-
## How to Use
19+
## Quick Start
1920

2021
using command line:
2122
```shell

‎docs/index.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# pyliquibase
2+
3+
A Python module to use [Liquibase](http://www.liquibase.org/) in Python, using the Java Native Interface (JNI).
4+
5+
pyliquibase allows you to execute Liquibase commands directly from your Python scripts or via the command line, providing a seamless integration between Python and Liquibase's powerful database schema evolution capabilities.
6+
7+
## Key Features
8+
9+
- **CLI Support**: Run Liquibase commands directly from your terminal.
10+
- **Python API**: Integrate Liquibase into your Python applications with a simple and intuitive API.
11+
- **JNI Integration**: Uses JPype to bridge Python and Java, ensuring high performance and compatibility.
12+
- **Database Agnostic**: Works with any database supported by Liquibase.
13+
14+
## Python Java Integration
15+
16+
This library leverages [JPype1](https://github.com/jpype-project/jpype) to interact with the Java `LiquibaseCommandLine` class. It starts a Java Virtual Machine (JVM) and passes Liquibase calls to the Java execution engine.
17+
18+
```mermaid
19+
graph TD
20+
A[Python Script] --> B[pyliquibase API]
21+
B --> C[JPype JNI Bridge]
22+
C --> D[Java Virtual Machine]
23+
D --> E[Liquibase Java Core]
24+
E --> F[Target Database]
25+
```

‎docs/installation.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Installation
2+
3+
Getting started with `pyliquibase` is straightforward.
4+
5+
## Prerequisites
6+
7+
Python-Java integration requires **Java**. Ensure Java is installed and configured on your operating system.
8+
9+
!!! note
10+
You can check if Java is installed by running `java -version` in your terminal.
11+
12+
## Install via pip
13+
14+
The easiest way to install `pyliquibase` is using `pip`:
15+
16+
```bash
17+
pip install pyliquibase
18+
```
19+
20+
## Verify Installation
21+
22+
After installation, you can verify that the `pyliquibase` command-line tool is available:
23+
24+
```bash
25+
pyliquibase --version
26+
```

‎docs/usage.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Usage
2+
3+
`pyliquibase` can be used either as a command-line tool or as a library within your Python scripts.
4+
5+
## Command Line Interface (CLI)
6+
7+
You can run Liquibase commands directly from the shell. A common pattern is to use a `liquibase.properties` file for configuration.
8+
9+
```bash
10+
pyliquibase --defaultsFile=changelogs/liquibase.properties status
11+
pyliquibase --defaultsFile=changelogs/liquibase.properties validate
12+
pyliquibase --defaultsFile=changelogs/liquibase.properties updateSQL
13+
pyliquibase --defaultsFile=changelogs/liquibase.properties update
14+
```
15+
16+
## Python API
17+
18+
Using `pyliquibase` in your Python code is simple.
19+
20+
### Basic Example
21+
22+
```python
23+
from pyliquibase import Pyliquibase
24+
25+
if __name__ == '__main__':
26+
# Initialize with a properties file
27+
liquibase = Pyliquibase(defaultsFile="changelogs/liquibase.properties", logLevel="INFO")
28+
29+
# Execute specific commands
30+
liquibase.status()
31+
liquibase.validate()
32+
liquibase.update()
33+
```
34+
35+
### Advanced Usage
36+
37+
You can also use the generic `execute` method to run any Liquibase command:
38+
39+
```python
40+
# Call execute with arguments
41+
liquibase.execute("status")
42+
liquibase.execute("rollback", "MyTag")
43+
44+
# Specific helper methods
45+
liquibase.update_to_tag("MyTag")
46+
liquibase.rollback("MyTag")
47+
48+
# Maintenance commands
49+
liquibase.changelog_sync()
50+
liquibase.clear_checksums()
51+
liquibase.release_locks()
52+
```

‎mkdocs.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
site_name: pyliquibase
2+
site_url: https://memiiso.github.io/pyliquibase
3+
repo_url: https://github.com/memiiso/pyliquibase
4+
edit_uri: edit/main/docs/
5+
6+
theme:
7+
name: material
8+
palette:
9+
- media: "(prefers-color-scheme: light)"
10+
scheme: default
11+
primary: indigo
12+
accent: indigo
13+
toggle:
14+
icon: material/brightness-7
15+
name: Switch to dark mode
16+
- media: "(prefers-color-scheme: dark)"
17+
scheme: slate
18+
primary: indigo
19+
accent: indigo
20+
toggle:
21+
icon: material/brightness-4
22+
name: Switch to light mode
23+
features:
24+
- navigation.indexes
25+
- navigation.tabs
26+
- navigation.top
27+
- toc.integrate
28+
- content.code.copy
29+
- content.tabs.link
30+
31+
nav:
32+
- Home: index.md
33+
- Installation: installation.md
34+
- Usage: usage.md
35+
36+
markdown_extensions:
37+
- pymdownx.highlight:
38+
anchor_linenums: true
39+
line_spans: __span
40+
pygments_lang_class: true
41+
- pymdownx.inlinehilite
42+
- pymdownx.snippets
43+
- pymdownx.superfences
44+
- admonition
45+
- pymdownx.details
46+
- abbr
47+
- toc:
48+
permalink: true

0 commit comments

Comments
 (0)