Skip to content

Commit ba50872

Browse files
techousetechouse
authored
📝 docs (#116)
1 parent b0cdc38 commit ba50872

File tree

12 files changed

+380
-2
lines changed

12 files changed

+380
-2
lines changed

‎.github/workflows/docs.yml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Docs
2+
3+
on:
4+
workflow_dispatch:
5+
branches:
6+
- main
7+
workflow_call:
8+
9+
permissions:
10+
contents: write
11+
12+
jobs:
13+
docs:
14+
name: "Docs"
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: "3.x"
21+
cache: "pip"
22+
- name: Install package
23+
run: pip install -e .
24+
- name: Install Sphinx dependencies
25+
working-directory: docs
26+
run: pip install -r requirements.txt
27+
- name: Sphinx build
28+
working-directory: docs
29+
run: sphinx-build . _build
30+
- name: Deploy to GitHub Pages
31+
uses: peaceiris/actions-gh-pages@v4
32+
with:
33+
publish_branch: gh-pages
34+
github_token: ${{ secrets.GITHUB_TOKEN }}
35+
publish_dir: docs/_build/
36+
force_orphan: true

‎.github/workflows/publish.yml

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,12 @@ defaults:
1010
permissions: read-all
1111

1212
jobs:
13-
build-and-publish:
13+
test:
14+
uses: ./.github/workflows/test.yml
15+
secrets: inherit
16+
publish:
17+
needs: test
18+
name: "Publish"
1419
runs-on: ubuntu-latest
1520
environment:
1621
name: pypi
@@ -99,9 +104,15 @@ jobs:
99104
rm -rf dist
100105
rm -rf $CHANGELOG_PATH
101106
docker:
102-
needs: build-and-publish
107+
needs: [ test, publish ]
103108
permissions:
104109
packages: write
105110
contents: read
106111
uses: ./.github/workflows/docker.yml
112+
secrets: inherit
113+
docs:
114+
uses: ./.github/workflows/docs.yml
115+
needs: [ test, publish ]
116+
permissions:
117+
contents: write
107118
secrets: inherit

‎.github/workflows/test.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,15 @@ on:
77
pull_request:
88
branches:
99
- master
10+
workflow_call:
1011
defaults:
1112
run:
1213
shell: bash
1314
permissions: read-all
1415

1516
jobs:
1617
analyze:
18+
name: "Analyze"
1719
runs-on: ubuntu-latest
1820
steps:
1921
- uses: actions/checkout@v4
@@ -29,6 +31,7 @@ jobs:
2931
run: tox -e linters
3032
test:
3133
needs: analyze
34+
name: "Test"
3235
runs-on: ubuntu-latest
3336
strategy:
3437
matrix:

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/README.rst

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
Usage
2+
-----
3+
4+
Transfer SQLite to MySQL using the provided CLI options.
5+
6+
Options
7+
^^^^^^^
8+
9+
SQLite Options
10+
~~~~~~~~~~~~~~
11+
12+
- ``-f, --sqlite-file PATH``: SQLite3 database file [required]
13+
- ``-t, --sqlite-tables TUPLE``: Transfer only these specific tables (space separated table names). Implies ``--without-foreign-keys`` which inhibits the transfer of foreign keys.
14+
- ``-X, --without-foreign-keys``: Do not transfer foreign keys.
15+
- ``-W, --ignore-duplicate-keys``: Ignore duplicate keys. The default behavior is to create new ones with a numerical suffix, e.g. 'existing_key' -> 'existing_key_1'
16+
17+
MySQL Options
18+
~~~~~~~~~~~~~
19+
20+
- ``-d, --mysql-database TEXT``: MySQL database name [required]
21+
- ``-u, --mysql-user TEXT``: MySQL user [required]
22+
- ``-p, --prompt-mysql-password``: Prompt for MySQL password
23+
- ``--mysql-password TEXT``: MySQL password
24+
- ``-h, --mysql-host TEXT``: MySQL host. Defaults to localhost.
25+
- ``-P, --mysql-port INTEGER``: MySQL port. Defaults to 3306.
26+
- ``-S, --skip-ssl``: Disable MySQL connection encryption.
27+
- ``-i, --mysql-insert-method [UPDATE|IGNORE|DEFAULT]``: MySQL insert method. DEFAULT will throw errors when encountering duplicate records; UPDATE will update existing rows; IGNORE will ignore insert errors. Defaults to IGNORE.
28+
- ``-E, --mysql-truncate-tables``: Truncates existing tables before inserting data.
29+
- ``--mysql-integer-type TEXT``: MySQL default integer field type. Defaults to INT(11).
30+
- ``--mysql-string-type TEXT``: MySQL default string field type. Defaults to VARCHAR(255).
31+
- ``--mysql-text-type [MEDIUMTEXT|TEXT|TINYTEXT|LONGTEXT]``: MySQL default text field type. Defaults to TEXT.
32+
- ``--mysql-charset TEXT``: MySQL database and table character set [default: utf8mb4]
33+
- ``--mysql-collation TEXT``: MySQL database and table collation
34+
35+
Other Options
36+
~~~~~~~~~~~~~
37+
38+
- ``-T, --use-fulltext``: Use FULLTEXT indexes on TEXT columns. Will throw an error if your MySQL version does not support InnoDB FULLTEXT indexes!
39+
- ``--with-rowid``: Transfer rowid columns.
40+
- ``-c, --chunk INTEGER``: Chunk reading/writing SQL records
41+
- ``-l, --log-file PATH``: Log file
42+
- ``-q, --quiet``: Quiet. Display only errors.
43+
- ``--debug``: Debug mode. Will throw exceptions.
44+
- ``--version``: Show the version and exit.
45+
- ``--help``: Show this message and exit.
46+
47+
Docker
48+
^^^^^^
49+
50+
If you don’t want to install the tool on your system, you can use the
51+
Docker image instead.
52+
53+
.. code:: bash
54+
55+
docker run -it \
56+
--workdir $(pwd) \
57+
--volume $(pwd):$(pwd) \
58+
--rm ghcr.io/techouse/sqlite3-to-mysql:latest \
59+
--sqlite-file baz.db \
60+
--mysql-user foo \
61+
--mysql-password bar \
62+
--mysql-database baz \
63+
--mysql-host host.docker.internal
64+
65+
This will mount your host current working directory (pwd) inside the
66+
Docker container as the current working directory. Any files Docker
67+
would write to the current working directory are written to the host
68+
directory where you did docker run. Note that you have to also use a
69+
`special
70+
hostname <https://docs.docker.com/desktop/networking/#use-cases-and-workarounds-for-all-platforms>`__
71+
``host.docker.internal`` to access your host machine from inside the
72+
Docker container.
73+
74+
Homebrew
75+
^^^^^^^^
76+
77+
If you’re on macOS, you can install the tool using
78+
`Homebrew <https://brew.sh/>`__.
79+
80+
.. code:: bash
81+
82+
brew tap techouse/sqlite3-to-mysql
83+
brew install sqlite3-to-mysql
84+
sqlite3mysql --help

‎docs/conf.py

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
import os
6+
import sys
7+
8+
9+
sys.path.insert(0, os.path.abspath(".."))
10+
11+
from sqlite3_to_mysql import __version__
12+
13+
14+
# -- Project information -----------------------------------------------------
15+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
16+
17+
project = "sqlite3-to-mysql"
18+
copyright = "2024, Klemen Tusar"
19+
author = "Klemen Tusar"
20+
release = __version__
21+
22+
# -- General configuration ---------------------------------------------------
23+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
24+
25+
extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.napoleon"]
26+
27+
napoleon_google_docstring = True
28+
napoleon_include_init_with_doc = True
29+
30+
templates_path = ["_templates"]
31+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
32+
33+
34+
# -- Options for HTML output -------------------------------------------------
35+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
36+
37+
html_theme = "alabaster"
38+
html_static_path = ["_static"]

‎docs/index.rst

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
SQLite3 to MySQL
2+
================
3+
4+
A simple Python tool to transfer data from SQLite 3 to MySQL
5+
6+
|PyPI| |PyPI - Downloads| |PyPI - Python Version| |MySQL Support| |MariaDB Support|
7+
|GitHub license| |Contributor Covenant| |PyPI - Format| |Code style: black|
8+
|Codacy Badge| |Test Status| |CodeQL Status| |Publish PyPI Package Status|
9+
|Publish Docker Image| |codecov| |GitHub Sponsors| |GitHub stars|
10+
11+
Installation
12+
------------
13+
14+
.. code:: bash
15+
16+
pip install sqlite3-to-mysql
17+
18+
Basic Usage
19+
-----------
20+
21+
.. code:: bash
22+
23+
sqlite3mysql -f path/to/foo.sqlite -d foo_db -u foo_user -p
24+
25+
.. toctree::
26+
:maxdepth: 4
27+
:caption: Contents:
28+
29+
README
30+
modules
31+
32+
Indices and tables
33+
==================
34+
35+
* :ref:`genindex`
36+
* :ref:`modindex`
37+
* :ref:`search`
38+
39+
.. |PyPI| image:: https://img.shields.io/pypi/v/sqlite3-to-mysql
40+
:target: https://pypi.org/project/sqlite3-to-mysql/
41+
.. |PyPI - Downloads| image:: https://img.shields.io/pypi/dm/sqlite3-to-mysql
42+
:target: https://pypistats.org/packages/sqlite3-to-mysql
43+
.. |PyPI - Python Version| image:: https://img.shields.io/pypi/pyversions/sqlite3-to-mysql
44+
:target: https://pypi.org/project/sqlite3-to-mysql/
45+
.. |MySQL Support| image:: https://img.shields.io/static/v1?label=MySQL&message=5.5+%7C+5.6+%7C+5.7+%7C+8.0&color=2b5d80
46+
:target: https://img.shields.io/static/v1?label=MySQL&message=5.6+%7C+5.7+%7C+8.0&color=2b5d80
47+
.. |MariaDB Support| image:: https://img.shields.io/static/v1?label=MariaDB&message=5.5+%7C+10.0+%7C+10.1+%7C+10.2+%7C+10.3+%7C+10.4+%7C+10.5+%7C+10.6%7C+10.11&color=C0765A
48+
:target: https://img.shields.io/static/v1?label=MariaDB&message=10.0+%7C+10.1+%7C+10.2+%7C+10.3+%7C+10.4+%7C+10.5&color=C0765A
49+
.. |GitHub license| image:: https://img.shields.io/github/license/techouse/sqlite3-to-mysql
50+
:target: https://github.com/techouse/sqlite3-to-mysql/blob/master/LICENSE
51+
.. |Contributor Covenant| image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
52+
:target: CODE-OF-CONDUCT.md
53+
.. |PyPI - Format| image:: https://img.shields.io/pypi/format/sqlite3-to-mysql
54+
:target: (https://pypi.org/project/sqlite3-to-mysql/)
55+
.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
56+
:target: https://github.com/ambv/black
57+
.. |Codacy Badge| image:: https://api.codacy.com/project/badge/Grade/d33b59d35b924711aae9418741a923ae
58+
:target: https://www.codacy.com/manual/techouse/sqlite3-to-mysql?utm_source=github.com&utm_medium=referral&utm_content=techouse/sqlite3-to-mysql&utm_campaign=Badge_Grade
59+
.. |Test Status| image:: https://github.com/techouse/sqlite3-to-mysql/actions/workflows/test.yml/badge.svg
60+
:target: https://github.com/techouse/sqlite3-to-mysql/actions/workflows/test.yml
61+
.. |CodeQL Status| image:: https://github.com/techouse/sqlite3-to-mysql/actions/workflows/codeql-analysis.yml/badge.svg
62+
:target: https://github.com/techouse/sqlite3-to-mysql/actions/workflows/codeql-analysis.yml
63+
.. |Publish PyPI Package Status| image:: https://github.com/techouse/sqlite3-to-mysql/actions/workflows/publish.yml/badge.svg
64+
:target: https://github.com/techouse/sqlite3-to-mysql/actions/workflows/publish.yml
65+
.. |Publish Docker Image| image:: https://github.com/techouse/sqlite3-to-mysql/actions/workflows/docker.yml/badge.svg
66+
:target: https://github.com/techouse/sqlite3-to-mysql/actions/workflows/docker.yml
67+
.. |codecov| image:: https://codecov.io/gh/techouse/sqlite3-to-mysql/branch/master/graph/badge.svg
68+
:target: https://codecov.io/gh/techouse/sqlite3-to-mysql
69+
.. |GitHub Sponsors| image:: https://img.shields.io/github/sponsors/techouse
70+
:target: https://github.com/sponsors/techouse
71+
.. |GitHub stars| image:: https://img.shields.io/github/stars/techouse/sqlite3-to-mysql.svg?style=social&label=Star&maxAge=2592000
72+
:target: https://github.com/techouse/sqlite3-to-mysql/stargazers

‎docs/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/modules.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
sqlite3_to_mysql
2+
================
3+
4+
.. toctree::
5+
:maxdepth: 4
6+
7+
sqlite3_to_mysql

‎docs/requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Sphinx==7.3.7

0 commit comments

Comments
 (0)