This package is currently in beta. It is meant to render paralex lexicon files in mkdocs sites.
# Installing
```bash
pip install mkdocs_paralex_plugin
```
# Quick start
Create a configuration file for [mkdocs](https://www.mkdocs.org/user-guide/), compatible with [mkdocs-material](https://squidfunk.github.io/mkdocs-material/).
It needs a special `paralex` section, with minimally a `paralex_package_path` (to the json file), lists of feature labels to use to separate tables, rows and columns. It can contain
``` yaml title="mkdocs.yml"
site_name: "My site name"
docs_dir: docs
plugins:
- paralex:
paralex_package_path: "<name>.package.json"
layout_tables:
- mood
layout_rows:
- person/number
layout_columns:
- tense
repo_url: https://gitlab.com/<user>/<repo>
```
# Large datasets
If your lexicon is massive, the generated site might exceed the free hosting capacity on gitlab or github. There is then two options: compressing some assets (should still work with most browsers), and if that is still not enough, serving just a sample of the data.
## Compressing some assets
An easy way for the static site to take less space is to compress some assets. Just add a `compress: true` key:
``` yaml title="mkdocs.yml"
site_name: "My site name"
docs_dir: docs
plugins:
- paralex:
paralex_package_path: "<name>.package.json"
compress: true
layout_tables:
- mood
layout_rows:
- person/number
layout_columns:
- tense
repo_url: https://gitlab.com/<user>/<repo>
```
## Presenting only a sample of the data
To limit the site generation to a sample of the data, you need two more keys under the paralex section. If `sample_size` is set, the corresponding number of lexemes will be selected, and the site will only show that sample. If `frequency_sample` is set to `true`, then the chosen lexemes will be the most frequent.
``` yaml title="mkdocs.yml"
site_name: "My site name"
docs_dir: docs
plugins:
- paralex:
paralex_package_path: "<name>.package.json"
sample_size: 5000
frequency_sample: true
layout_tables:
- mood
layout_rows:
- person/number
layout_columns:
- tense
repo_url: https://gitlab.com/<user>/<repo>
```
# Hosting on gitlab
To generate the site, add a plain text file called `.gitlab-ci.yml`, with the following content. The site will then be served at `https://<username>.gitlab.io/<repository-name>`. For more on gitlab pages, see [the gitlab pages docs](https://docs.gitlab.com/ee/user/project/pages/).
``` yaml title=".gitlab-ci.yml"
image: python:3.8
pages:
stage: deploy
script:
- mkdir -p docs/
- pip install pandas mkdocs>=1.1.2 mkdocs-material mkdocs_paralex_plugin
- mkdocs build -d public/ --strict --verbose
artifacts:
paths:
- public/
only:
- master
```
# Github pages
To generate for github pages, see the [mkdocs documentation](https://www.mkdocs.org/user-guide/deploying-your-docs/). In brief, checkout the `main` or `master` branch of your project, locally install the needed packages, then run the github pages builder:
```bash
mkdir -p docs/
pip install pandas mkdocs>=1.1.2 mkdocs-material mkdocs_paralex_plugin
mkdocs gh-deploy
```
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/sbeniamine/paralex-site/",
"name": "mkdocs-paralex-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mkdocs",
"author": "Sacha Beniamine",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b9/8c/6553481ce65fa49d0dc2aca141eef58a903563d81f698acc8a57faf926f5/mkdocs_paralex_plugin-0.1.12b0.tar.gz",
"platform": null,
"description": "\nThis package is currently in beta. It is meant to render paralex lexicon files in mkdocs sites.\n\n# Installing\n\n```bash\npip install mkdocs_paralex_plugin\n```\n\n# Quick start \n\nCreate a configuration file for [mkdocs](https://www.mkdocs.org/user-guide/), compatible with [mkdocs-material](https://squidfunk.github.io/mkdocs-material/). \n\nIt needs a special `paralex` section, with minimally a `paralex_package_path` (to the json file), lists of feature labels to use to separate tables, rows and columns. It can contain \n\n``` yaml title=\"mkdocs.yml\"\nsite_name: \"My site name\"\ndocs_dir: docs\nplugins:\n - paralex:\n paralex_package_path: \"<name>.package.json\"\n layout_tables:\n - mood\n layout_rows:\n - person/number\n layout_columns:\n - tense\nrepo_url: https://gitlab.com/<user>/<repo>\n```\n\n# Large datasets\n\nIf your lexicon is massive, the generated site might exceed the free hosting capacity on gitlab or github. There is then two options: compressing some assets (should still work with most browsers), and if that is still not enough, serving just a sample of the data.\n\n## Compressing some assets\n\nAn easy way for the static site to take less space is to compress some assets. Just add a `compress: true` key:\n\n``` yaml title=\"mkdocs.yml\"\nsite_name: \"My site name\"\ndocs_dir: docs\nplugins:\n - paralex:\n paralex_package_path: \"<name>.package.json\"\n compress: true\n layout_tables:\n - mood\n layout_rows:\n - person/number\n layout_columns:\n - tense\nrepo_url: https://gitlab.com/<user>/<repo>\n```\n\n## Presenting only a sample of the data \n\nTo limit the site generation to a sample of the data, you need two more keys under the paralex section. If `sample_size` is set, the corresponding number of lexemes will be selected, and the site will only show that sample. If `frequency_sample` is set to `true`, then the chosen lexemes will be the most frequent.\n\n``` yaml title=\"mkdocs.yml\"\nsite_name: \"My site name\"\ndocs_dir: docs\nplugins:\n - paralex:\n paralex_package_path: \"<name>.package.json\"\n sample_size: 5000\n frequency_sample: true\n layout_tables:\n - mood\n layout_rows:\n - person/number\n layout_columns:\n - tense\nrepo_url: https://gitlab.com/<user>/<repo>\n```\n\n# Hosting on gitlab\n\nTo generate the site, add a plain text file called `.gitlab-ci.yml`, with the following content. The site will then be served at `https://<username>.gitlab.io/<repository-name>`. For more on gitlab pages, see [the gitlab pages docs](https://docs.gitlab.com/ee/user/project/pages/). \n\n``` yaml title=\".gitlab-ci.yml\"\nimage: python:3.8\n\npages:\n stage: deploy\n script:\n - mkdir -p docs/\n - pip install pandas mkdocs>=1.1.2 mkdocs-material mkdocs_paralex_plugin\n - mkdocs build -d public/ --strict --verbose\n artifacts:\n paths:\n - public/\n only:\n - master\n```\n\n# Github pages\n\nTo generate for github pages, see the [mkdocs documentation](https://www.mkdocs.org/user-guide/deploying-your-docs/). In brief, checkout the `main` or `master` branch of your project, locally install the needed packages, then run the github pages builder:\n\n```bash\nmkdir -p docs/\npip install pandas mkdocs>=1.1.2 mkdocs-material mkdocs_paralex_plugin\nmkdocs gh-deploy\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Build static sites for paralex lexicons",
"version": "0.1.12b0",
"project_urls": {
"Homepage": "https://gitlab.com/sbeniamine/paralex-site/"
},
"split_keywords": [
"mkdocs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "30f081a53b9a7c5e5bd71620ba9023aa3f2fd9ab4edf3bb19067400201b7664c",
"md5": "d01b158a56cf7286166883118fde6af4",
"sha256": "811612738301248c5f5647d486152348168702520fd544a765ac5efa71a438e1"
},
"downloads": -1,
"filename": "mkdocs_paralex_plugin-0.1.12b0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d01b158a56cf7286166883118fde6af4",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 26204,
"upload_time": "2024-11-28T10:17:40",
"upload_time_iso_8601": "2024-11-28T10:17:40.406907Z",
"url": "https://files.pythonhosted.org/packages/30/f0/81a53b9a7c5e5bd71620ba9023aa3f2fd9ab4edf3bb19067400201b7664c/mkdocs_paralex_plugin-0.1.12b0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b98c6553481ce65fa49d0dc2aca141eef58a903563d81f698acc8a57faf926f5",
"md5": "f2967425ecd32f04c8a0ae0db3b45fd4",
"sha256": "0e7954ce7150a9669caeb3b76f075e8d560ba49a640424459622286ef5372d7f"
},
"downloads": -1,
"filename": "mkdocs_paralex_plugin-0.1.12b0.tar.gz",
"has_sig": false,
"md5_digest": "f2967425ecd32f04c8a0ae0db3b45fd4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26884,
"upload_time": "2024-11-28T10:17:41",
"upload_time_iso_8601": "2024-11-28T10:17:41.443006Z",
"url": "https://files.pythonhosted.org/packages/b9/8c/6553481ce65fa49d0dc2aca141eef58a903563d81f698acc8a57faf926f5/mkdocs_paralex_plugin-0.1.12b0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-28 10:17:41",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "sbeniamine",
"gitlab_project": "paralex-site",
"lcname": "mkdocs-paralex-plugin"
}
JSON