| Name | kolibri-explore-plugin JSON |
| Version |
7.15.0
JSON |
| download |
| home_page | |
| Summary | Kolibri plugin for Endless custom presentation |
| upload_time | 2024-02-09 23:19:56 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.3 |
| license | MIT License Copyright (c) 2021–2023 Endless OS Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
kolibri
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Kolibri Explore Plugin
This plugin adds the Endless Key experience on top of Kolibri:
- A content navigation view exposed in the `/explore` URL. As an
alternative to the Kolibri Learn plugin for self-guided learners.
- Branding and layout customizations for several channels.
- Download of content packs with extra metadata.
## Usage
This is a plugin for Kolibri, so it must be installed in your Kolibri
environment.
Install latest release from PyPi:
```
pip install kolibri-explore-plugin
```
Then enable it in Kolibri and run migrations:
```
kolibri plugin enable kolibri_explore_plugin
kolibri manage migrate
```
Download the `apps-bundle.zip` from the [GitHub releases
page](https://github.com/endlessm/kolibri-explore-plugin/releases) and
extract them to the `kolibri_explore_plugin/apps` folder. Note that
this is not ideal, because you should know where has `pip` installed
the plugin.
Download the JSON files from the
[endless-key-collections](https://github.com/endlessm/endless-key-collections/tree/main/json)
repo and place them in `kolibri_explore_plugin/static/collections/`.
Now start Kolibri. You should be able to navigate to `/explore` if `/`
doesn't redirect you already.
## Setup
Make sure you already have the **latest** `pipenv`.
Either if you want to build or develop the plugin, please run:
```
./scripts/bootstrap.sh
```
Just like Kolibri, we use a Python virtual environment along with Node
to obtain the exact same dependencies.
## Building
### Creating the `.whl` file
With all the dependencies installed, it's now possible to build the
plugin by running:
```
yarn build-dist
```
A `.whl` file will be created in the `dist/` folder. You
can then install it:
```
pip install dist/kolibri_explore_plugin-*.whl
```
## Testing
### Backend tests
Tests for the Python backend can be run by executing `python -m pytest`
or `yarn run test:python`. See the plugin
[`test`](kolibri_explore_plugin/test) directory for more details about
the Python testing infrastructure.
## Development
### Getting started with development
For developing you could build and install the `.whl` file over and
over for each iteration. But is much easier to install the project in
editable mode, which basically creates a symlink:
```
pip install --editable .
```
**Note:** you still need to enable the plugin and run migrations as in
Usage above!
Then serve the plugin in watch mode:
```
yarn dev
```
Usually you will also be developing Kolibri, as described in
[the Kolibri developer documentation](https://kolibri-dev.readthedocs.io/en/develop/getting_started.html).
So probably you have the following running in another Terminal tab:
```
yarn run devserver-hot
```
And you can edit both the plugin and Kolibri in live-mode. Further,
you can also edit a custom channel presentation in another Terminal
tab. See "Developing custom channel presentations" section below.
### Configuring the precommit hook
To run checks before any commit just run this command:
```
pre-commit install -f --install-hooks
```
There is a continuous integration tool in Github that will run the
same checks for each pull request.
### Bundling custom channel presentations
There is a Github action that does this automatically on each
release. To do it locally yourself:
```
yarn build:apps
```
All custom presentation app bundles should be added in the
`kolibri_explore_plugin/apps` directory to have this fully working.
The zip bundle should be named `custom-channel-ui.zip` and it should
be placed inside the corresponding app folder.
### Developing custom channel presentations
Instead of bundling the custom channel presentation inside the apps
directory, it's possible to work with a proxy for development. Note
that the proxy will be used for all the channels, not only for the
channel in question.
1. Run the custom channel presentation development server. For
instance to run the template:
```bash
$ cd packages/template-ui
$ yarn serve
```
2. Run Kolibri with the `PROXY_CUSTOM_CHANNEL` environment variable
enabled:
```bash
$ cd /PATH/TO/kolibri
$ PROXY_CUSTOM_CHANNEL=1 yarn run devserver-hot
```
Every request to the `custom-channel-ui.zip` will be proxied to the
devserver. The hot reloading should work here too!
### Ingesting highlighted content
Make sure to have a `.env` file with the spreadsheet key as content:
```bash
CONTENT_SPREADSHEET_KEY=123456
```
Then run the script:
```
./scripts/ingest_highlighted.py
```
If everything goes well, the `highlighted-content.json` file will be
updated. You then need to commit the file.
### Releasing
#### Release with GitHub action
Triggering [Bump version to release](https://github.com/endlessm/kolibri-explore-plugin/actions/workflows/bump2release.yml)
action from `bump2release.yml` will do all release steps mentioned in
[Release with local environment](#release-with-local-environment)
automatically, including:
* Bump version and create a new tag
* Publish kolibri-explore-plugin wheel package to PyPI
* Release apps-bundle.zip
#### Release with local environment
To release a new version first please bump the version number to
either major or minor. Note that the major version also needs a version
name for branding. For example:
```bash
# For a minor release:
yarn bump-version minor
# For a major release:
yarn bump-version major "Komodo Dragon"
```
That creates a new commit and a git tag. Please push them to the
remote:
```bash
git push
git push origin NEW_TAG
```
The `bump-version` script can also be run with options such as
`--dry-run --list` or `--no-commit` to see what will happen. You can
also specify `--current-version` to see the effect without actually
changing the current version. See `bumpversion --help` for all options.
#### Release candidates
PyPI and `pip` support release candidates with the `rc<N>` suffix. Prior
to major releases it may be helpful to build and publish release
candidates so they can be tested prior to general availability. Our
`bumpversion` configuration has limited support for release candidates,
so care should be taken to ensure the new version comes out correctly.
To begin a release candidate series, the version must be fully specified:
```bash
yarn bump-version major "Komodo Dragon" --new-version 7.0.0rc1
```
To make the next release candidate, run:
``` bash
yarn bump-version rc
```
Finally, to end a release candidate series, the version must be fully
specified again:
``` bash
yarn bump-version major "Komodo Dragon" --new-version 7.0.0
```
In all cases, the commit and tag must be pushed to the remote as
explained above.
### How to display the build information
To show the build information in the front page, as a tag in top right corner,
you can set the environment variable, `SHOW_BUILD_INFO` to "true", for example,
for the development kolibri server:
```
$ SHOW_BUILD_INFO=true yarn run devserver
```
Raw data
{
"_id": null,
"home_page": "",
"name": "kolibri-explore-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.3",
"maintainer_email": "",
"keywords": "kolibri",
"author": "",
"author_email": "Endless OS Foundation <key@endlessos.org>",
"download_url": "https://files.pythonhosted.org/packages/5a/b3/2a62d8921f07492621d38bafb648b501b649d8d2450cfa16f1377cfc0b17/kolibri_explore_plugin-7.15.0.tar.gz",
"platform": null,
"description": "# Kolibri Explore Plugin\n\nThis plugin adds the Endless Key experience on top of Kolibri:\n\n- A content navigation view exposed in the `/explore` URL. As an\n alternative to the Kolibri Learn plugin for self-guided learners.\n\n- Branding and layout customizations for several channels.\n\n- Download of content packs with extra metadata.\n\n## Usage\n\nThis is a plugin for Kolibri, so it must be installed in your Kolibri\nenvironment.\n\nInstall latest release from PyPi:\n\n```\npip install kolibri-explore-plugin\n```\n\nThen enable it in Kolibri and run migrations:\n\n```\nkolibri plugin enable kolibri_explore_plugin\nkolibri manage migrate\n```\n\nDownload the `apps-bundle.zip` from the [GitHub releases\npage](https://github.com/endlessm/kolibri-explore-plugin/releases) and\nextract them to the `kolibri_explore_plugin/apps` folder. Note that\nthis is not ideal, because you should know where has `pip` installed\nthe plugin.\n\nDownload the JSON files from the\n[endless-key-collections](https://github.com/endlessm/endless-key-collections/tree/main/json)\nrepo and place them in `kolibri_explore_plugin/static/collections/`.\n\nNow start Kolibri. You should be able to navigate to `/explore` if `/`\ndoesn't redirect you already.\n\n## Setup\n\nMake sure you already have the **latest** `pipenv`.\n\nEither if you want to build or develop the plugin, please run:\n\n```\n./scripts/bootstrap.sh\n```\n\nJust like Kolibri, we use a Python virtual environment along with Node\nto obtain the exact same dependencies.\n\n## Building\n### Creating the `.whl` file\n\nWith all the dependencies installed, it's now possible to build the\nplugin by running:\n\n```\nyarn build-dist\n```\n\nA `.whl` file will be created in the `dist/` folder. You\ncan then install it:\n\n```\npip install dist/kolibri_explore_plugin-*.whl\n```\n\n## Testing\n### Backend tests\n\nTests for the Python backend can be run by executing `python -m pytest`\nor `yarn run test:python`. See the plugin\n[`test`](kolibri_explore_plugin/test) directory for more details about\nthe Python testing infrastructure.\n\n## Development\n### Getting started with development\n\nFor developing you could build and install the `.whl` file over and\nover for each iteration. But is much easier to install the project in\neditable mode, which basically creates a symlink:\n\n```\npip install --editable .\n```\n\n**Note:** you still need to enable the plugin and run migrations as in\nUsage above!\n\nThen serve the plugin in watch mode:\n\n```\nyarn dev\n```\n\nUsually you will also be developing Kolibri, as described in\n[the Kolibri developer documentation](https://kolibri-dev.readthedocs.io/en/develop/getting_started.html).\n\nSo probably you have the following running in another Terminal tab:\n\n```\nyarn run devserver-hot\n```\n\nAnd you can edit both the plugin and Kolibri in live-mode. Further,\nyou can also edit a custom channel presentation in another Terminal\ntab. See \"Developing custom channel presentations\" section below.\n\n### Configuring the precommit hook\n\nTo run checks before any commit just run this command:\n\n```\npre-commit install -f --install-hooks\n```\n\nThere is a continuous integration tool in Github that will run the\nsame checks for each pull request.\n\n### Bundling custom channel presentations\n\nThere is a Github action that does this automatically on each\nrelease. To do it locally yourself:\n\n```\nyarn build:apps\n```\n\nAll custom presentation app bundles should be added in the\n`kolibri_explore_plugin/apps` directory to have this fully working.\nThe zip bundle should be named `custom-channel-ui.zip` and it should\nbe placed inside the corresponding app folder.\n\n### Developing custom channel presentations\n\nInstead of bundling the custom channel presentation inside the apps\ndirectory, it's possible to work with a proxy for development. Note\nthat the proxy will be used for all the channels, not only for the\nchannel in question.\n\n1. Run the custom channel presentation development server. For\n instance to run the template:\n\n```bash\n$ cd packages/template-ui\n$ yarn serve\n```\n\n2. Run Kolibri with the `PROXY_CUSTOM_CHANNEL` environment variable\n enabled:\n\n```bash\n$ cd /PATH/TO/kolibri\n$ PROXY_CUSTOM_CHANNEL=1 yarn run devserver-hot\n```\n\nEvery request to the `custom-channel-ui.zip` will be proxied to the\ndevserver. The hot reloading should work here too!\n\n### Ingesting highlighted content\n\nMake sure to have a `.env` file with the spreadsheet key as content:\n\n```bash\nCONTENT_SPREADSHEET_KEY=123456\n```\n\nThen run the script:\n\n```\n./scripts/ingest_highlighted.py\n```\n\nIf everything goes well, the `highlighted-content.json` file will be\nupdated. You then need to commit the file.\n\n### Releasing\n\n#### Release with GitHub action\n\nTriggering [Bump version to release](https://github.com/endlessm/kolibri-explore-plugin/actions/workflows/bump2release.yml)\naction from `bump2release.yml` will do all release steps mentioned in\n[Release with local environment](#release-with-local-environment)\nautomatically, including:\n* Bump version and create a new tag\n* Publish kolibri-explore-plugin wheel package to PyPI\n* Release apps-bundle.zip\n\n#### Release with local environment\n\nTo release a new version first please bump the version number to\neither major or minor. Note that the major version also needs a version\nname for branding. For example:\n\n```bash\n# For a minor release:\nyarn bump-version minor\n\n# For a major release:\nyarn bump-version major \"Komodo Dragon\"\n```\n\nThat creates a new commit and a git tag. Please push them to the\nremote:\n\n```bash\ngit push\ngit push origin NEW_TAG\n```\n\nThe `bump-version` script can also be run with options such as\n`--dry-run --list` or `--no-commit` to see what will happen. You can\nalso specify `--current-version` to see the effect without actually\nchanging the current version. See `bumpversion --help` for all options.\n\n#### Release candidates\n\nPyPI and `pip` support release candidates with the `rc<N>` suffix. Prior\nto major releases it may be helpful to build and publish release\ncandidates so they can be tested prior to general availability. Our\n`bumpversion` configuration has limited support for release candidates,\nso care should be taken to ensure the new version comes out correctly.\n\nTo begin a release candidate series, the version must be fully specified:\n\n```bash\nyarn bump-version major \"Komodo Dragon\" --new-version 7.0.0rc1\n```\n\nTo make the next release candidate, run:\n\n``` bash\nyarn bump-version rc\n```\n\nFinally, to end a release candidate series, the version must be fully\nspecified again:\n\n``` bash\nyarn bump-version major \"Komodo Dragon\" --new-version 7.0.0\n```\n\nIn all cases, the commit and tag must be pushed to the remote as\nexplained above.\n\n### How to display the build information\n\nTo show the build information in the front page, as a tag in top right corner,\nyou can set the environment variable, `SHOW_BUILD_INFO` to \"true\", for example,\nfor the development kolibri server:\n\n```\n$ SHOW_BUILD_INFO=true yarn run devserver\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2021\u20132023 Endless OS Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Kolibri plugin for Endless custom presentation",
"version": "7.15.0",
"project_urls": {
"Bug Tracker": "https://github.com/endlessm/kolibri-explore-plugin/issues/",
"Homepage": "https://github.com/endlessm/kolibri-explore-plugin"
},
"split_keywords": [
"kolibri"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "803f0d58af7023211f0957ff5cac0d5ae04903ff35c099f1c0da075576817e2a",
"md5": "f1f479fb553478a9dbf4f51d8a0e4321",
"sha256": "f9412dcb465432a9f46f53886c4a93571c2bc66d78f588a06b9510b2ed0c1fb2"
},
"downloads": -1,
"filename": "kolibri_explore_plugin-7.15.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f1f479fb553478a9dbf4f51d8a0e4321",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.3",
"size": 26186674,
"upload_time": "2024-02-09T23:19:50",
"upload_time_iso_8601": "2024-02-09T23:19:50.821503Z",
"url": "https://files.pythonhosted.org/packages/80/3f/0d58af7023211f0957ff5cac0d5ae04903ff35c099f1c0da075576817e2a/kolibri_explore_plugin-7.15.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ab32a62d8921f07492621d38bafb648b501b649d8d2450cfa16f1377cfc0b17",
"md5": "64ecb4c42a92fd954f82d5d49c3195af",
"sha256": "b83ee1da452963ef9fe9f1dc3bb375a2cb05f8340090448bd4f8f988051e9fb3"
},
"downloads": -1,
"filename": "kolibri_explore_plugin-7.15.0.tar.gz",
"has_sig": false,
"md5_digest": "64ecb4c42a92fd954f82d5d49c3195af",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.3",
"size": 32588229,
"upload_time": "2024-02-09T23:19:56",
"upload_time_iso_8601": "2024-02-09T23:19:56.517949Z",
"url": "https://files.pythonhosted.org/packages/5a/b3/2a62d8921f07492621d38bafb648b501b649d8d2450cfa16f1377cfc0b17/kolibri_explore_plugin-7.15.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-09 23:19:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "endlessm",
"github_project": "kolibri-explore-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kolibri-explore-plugin"
}
