# mkdocs-sql
A MkDocs plugin for executing and embedding output of SQL queries in your documentation.
## Features
- Embed output of SQL queries in your markdown files
- Support for SQLite databases
- Display results as formatted tables
- Error handling and display
- Database configuration via mkdocs.yml
- Live updates - changes to database reflect immediately in documentation
- Toggle SQL queries on/off
- Toggle between formatted and raw markdown views
## Installation
```bash
pip install mkdocs-sql
```
## Usage
1. Add to mkdocs.yml:
```yaml
plugins:
- sql:
databasePath:
type: sqlite
path: ./path/to/database.file
```
2. In your markdown files:
```markdown
---
databasePath: ./relative/path/to/database.file
showQuery: true # optional, defaults to true
---
```sql
SELECT * FROM users LIMIT 5;
```
```
## Example Database Management
The plugin comes with a sample population database and management script. You can use it to test live updates:
```bash
# Reset database to initial state
python docs/examples/create_sample_db.py --reset
# Update a city's population (±10% random change)
python docs/examples/create_sample_db.py --update-city "New York"
# Update a country's population (±5% random change)
python docs/examples/create_sample_db.py --update-country "United States"
```
Changes to the database are reflected immediately in the documentation - just refresh the page!
## Configuration
| Option | Description | Default |
|--------|-------------|---------|
| databasePath.type | Database type (currently only sqlite) | sqlite |
| databasePath.path | Path to database file | None |
| showQuery | Show SQL queries by default | true |
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/ivishalgandhi/mkdocs-sql",
"name": "mkdocs-sql",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Vishal Gandhi",
"author_email": "Vishal Gandhi <igandhivishal@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/61/a3/44b427f4d0401324fff517c200db39ca9ab0837e6938bc77d5b16388e99a/mkdocs_sql-0.2.4.tar.gz",
"platform": null,
"description": "# mkdocs-sql\n\nA MkDocs plugin for executing and embedding output of SQL queries in your documentation.\n\n## Features\n\n- Embed output of SQL queries in your markdown files\n- Support for SQLite databases\n- Display results as formatted tables\n- Error handling and display\n- Database configuration via mkdocs.yml\n- Live updates - changes to database reflect immediately in documentation\n- Toggle SQL queries on/off\n- Toggle between formatted and raw markdown views\n\n## Installation\n\n```bash\npip install mkdocs-sql\n```\n\n## Usage\n\n1. Add to mkdocs.yml:\n```yaml\nplugins:\n - sql:\n databasePath:\n type: sqlite\n path: ./path/to/database.file\n```\n\n2. In your markdown files:\n```markdown\n---\ndatabasePath: ./relative/path/to/database.file\nshowQuery: true # optional, defaults to true\n---\n\n```sql\nSELECT * FROM users LIMIT 5;\n```\n```\n\n## Example Database Management\n\nThe plugin comes with a sample population database and management script. You can use it to test live updates:\n\n```bash\n# Reset database to initial state\npython docs/examples/create_sample_db.py --reset\n\n# Update a city's population (\u00b110% random change)\npython docs/examples/create_sample_db.py --update-city \"New York\"\n\n# Update a country's population (\u00b15% random change)\npython docs/examples/create_sample_db.py --update-country \"United States\"\n```\n\nChanges to the database are reflected immediately in the documentation - just refresh the page!\n\n## Configuration\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| databasePath.type | Database type (currently only sqlite) | sqlite |\n| databasePath.path | Path to database file | None |\n| showQuery | Show SQL queries by default | true |\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": null,
"summary": "A MkDocs plugin for executing and displaying SQL queries",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/ivishalgandhi/mkdocs-sql",
"Issues": "https://github.com/ivishalgandhi/mkdocs-sql/issues",
"Repository": "https://github.com/ivishalgandhi/mkdocs-sql"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "683936662496c2def5d6df4538564d95b27917955b76e63a9be843476b8f66ea",
"md5": "09269302f5dd74a8cfdb8184265c499a",
"sha256": "2e74d132931c551d4628593d4832db3560f535b174218559bb97994a26604ba2"
},
"downloads": -1,
"filename": "mkdocs_sql-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "09269302f5dd74a8cfdb8184265c499a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6004,
"upload_time": "2024-11-18T04:04:50",
"upload_time_iso_8601": "2024-11-18T04:04:50.685024Z",
"url": "https://files.pythonhosted.org/packages/68/39/36662496c2def5d6df4538564d95b27917955b76e63a9be843476b8f66ea/mkdocs_sql-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "61a344b427f4d0401324fff517c200db39ca9ab0837e6938bc77d5b16388e99a",
"md5": "aa7ba38db1d0369477b2cfbef8af6a7e",
"sha256": "16057685fca97ca8c270687e52db50158495e0dc4f863f4897f43c75a8f0fbc4"
},
"downloads": -1,
"filename": "mkdocs_sql-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "aa7ba38db1d0369477b2cfbef8af6a7e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7179,
"upload_time": "2024-11-18T04:04:51",
"upload_time_iso_8601": "2024-11-18T04:04:51.646974Z",
"url": "https://files.pythonhosted.org/packages/61/a3/44b427f4d0401324fff517c200db39ca9ab0837e6938bc77d5b16388e99a/mkdocs_sql-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-18 04:04:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ivishalgandhi",
"github_project": "mkdocs-sql",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mkdocs",
"specs": [
[
"==",
"1.6.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.2.3"
]
]
},
{
"name": "tabulate",
"specs": [
[
"==",
"0.9.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "build",
"specs": [
[
"==",
"1.0.3"
]
]
},
{
"name": "twine",
"specs": [
[
"==",
"4.0.2"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.4.4"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"4.1.0"
]
]
},
{
"name": "black",
"specs": [
[
"==",
"24.1.1"
]
]
},
{
"name": "isort",
"specs": [
[
"==",
"5.13.2"
]
]
},
{
"name": "flake8",
"specs": [
[
"==",
"7.0.0"
]
]
},
{
"name": "mkdocs-material",
"specs": [
[
"==",
"9.5.4"
]
]
},
{
"name": "mkdocs-material-extensions",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "pymdown-extensions",
"specs": [
[
"==",
"10.7"
]
]
},
{
"name": "mkdocstrings",
"specs": [
[
"==",
"0.24.0"
]
]
}
],
"lcname": "mkdocs-sql"
}
JSON
