ka-lite-zim

https://travis-ci.org/benjaoming/ka-lite-zim.png?branch=master https://readthedocs.org/projects/ka-lite-zim/badge/?version=latest

OpenZIM export command for ka-lite.

Features

  • Exporting the contents of a local KA Lite installation to the OpenZim
  • Easy to customize since you use KA Lite to select and download videos
  • Creates a .zim file with a single-page webapp containing video player and simple JS-based UI for filtering and searching the videos

Use case and contributions

This project is a Python project but is NOT on PyPi because it’s not intended for a wider audience. So just get the latest master, it should work with the latest KA Lite release. Please contribute to this project if you have changes to the .zim files that are available on the Kiwix website

The goal of this command is to build an alternative use case of Khan Academy for the popular offline reader Kiwix, which works for the open standards format OpenZim. Thus, it can benefit from the data prepared through the KA Lite software.

While KA Lite is truly built for education, Kiwix is more of an eLibrary. While Kiwix and OpenZim is more static, KA Lite has its focus on interaction.

Future

The export command for KA Lite is the immediate and easiest target. But we hope to be able to understand the OpenZIM format well enough to build an import command as well such that KA Lite students can interact with the data packaged and distributed by zim-packagers.

Contents:

Installation

  1. Clone from the Git repository:

    git clone https://github.com/benjaoming/ka-lite-zim.git

  2. Make sure that while you’re installing you are using the same Python environment (virtualenv?) that you also run KA Lite in.

  3. To install a fresh KA Lite together with ka-lite-zim, you should use virtualenv

    pip install virtualenv      # Installs virtualenv
                            # ...prepend "sudo" for system-wide
cd ka-lite-zim/             # Go to the source folder
virtualenv ./venv           # Creates a new virtualenv in ./venv
source ./venv/bin/activate  # Activates the virtualenv
pip install -e .            # Installs an editable

    If you already have KA Lite installed on your system, just CD to the directory and run the installer, provided that you have already activated the environment that KA Lite runs in:

    cd ka-lite-zim/
python setup.py install  # Add sudo in front if KA Lite is installed system-wide

  4. Make sure you have KA Lite installed and that you have issued kalite start at least once. Then edit your ~/.kalite/settings.py to contain this:

    from kalite.project.settings.base import *

INSTALLED_APPS += [
    'kalite_zim',
    'compressor',
]

Note

If you install as an editable with pip install -e ., then issuing git pull && pip install -e . from the source directory is enough to update the software. But remember the latter as dependencies might have changed.

Warning

If you install as an editable with, you cannot delete the source directory after installing!!

Warning

We require a specific version of KA Lite for ka-lite-zim. Therefore, if you already have KA Lite on the system, we recommend a virtualenv.

Usage

Note

Your system should have /usr/bin/ffmpeg available to generate thumbnails on the fly. There are several thumbnails missing in the collection so this is recommended.

To see all options, run:

kalite manage help export2zim
Manually select videos

  1. Run kalite start and go to your browser, setting up KA Lite and selecting the videos you need and downloading them.

  2. When KA Lite has the videos, you want, run this command

    kalite manage export2zim –language=en output.zim

Automatically downloading all videos

  1. Run kalite start, you may run kalite stop after, but the server has to be initialized firstly.

  2. To download a language pack for KA Lite without using the interface, run:

    kalite manage languagepackdownload --language=en --commandline

  3. Now you can run the OpenZim export command like this:

    kalite manage export2zim --language=en --download output.zim

Note

We use a temporary directory to create the .zim file and hard link all the videos. Therefore, if your /tmp folder and KA Lite data are on different devices, you can have problems. Use --tmp-dir=./tmp to specify a different location for temporary files.

Warning

We first created ka-lite-zim for ka-lite 0.15.x, and in case you are running an older version of KA Lite or the unreleased 0.16, you should take care if these versions of ka-lite already store data in ~/.kalite. Run commands differently to use different home directories, e.g. KALITE_HOME=~/.kalite_zim kalite manage start and KALITE_HOME=~/.kalite_zim kalite manage export2zim

Remember your also need to change settings.py in the new user folder.

Testing

The data sets are quite huge, so if you are developing and testing, use the --test flag and everything uses bogus JSON source data.

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions
Report Bugs

Report bugs at https://github.com/benjaoming/ka-lite-zim/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.
Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation

ka-lite-zim could always use more documentation, whether as part of the official ka-lite-zim docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/benjaoming/ka-lite-zim/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!

Ready to contribute? Here’s how to set up ka-lite-zim for local development.

  1. Fork the ka-lite-zim repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/ka-lite-zim.git

  3. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

  1. When you’re done making changes, check that your changes pass style and unit tests, including testing other Python versions with tox:

    $ tox

To get tox, just pip install it.

  1. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  2. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check https://travis-ci.org/benjaoming/ka-lite-zim under pull requests for active pull requests or run the tox command and make sure that the tests pass for all supported Python versions.
Tips

To run a subset of tests:

$ py.test test/test_ka-lite-zim.py

Credits

Development Lead
Contributors

None yet. Why not be the first?

History

0.1.0 (2016-01-04)
  • First release on PyPI.

Feedback

If you have any suggestions or questions about ka-lite-zim feel free to email me at benjamin@learningequality.org.

If you encounter any errors or problems with ka-lite-zim, please let me know! Open an Issue at the GitHub https://github.com/benjaoming/ka-lite-zim main repository.