A Server for Explaining the Unexplained
This Tutorons server provides a framework for running Tutorons, or code explainers, to add tooltip-style explanations to arbitrary web pages.
This project provides a lightweight implementation of the server to make it easy to get started.
For a heavier Tutorons server that supports more languages (but is tricker to set up), see andrewhead/tutorons-server.
Launch the server to explain code
Get the source
git clone --recursive https://github.com/andrewhead/tutorons-base.git cd tutorons-base
This clone includes both the server, and a reference implementation of on Tutoron: one that explains Python built-ins. This Tutoron is currently needed for checking some of the logic of successful requests (though we might phase it out later).
Install the dependencies
This tutorial assumes you are using Python 2.7. If you aren't, this code probably won't run.
We recommend installing all dependencies into a virtual environment so you can replicate our runtime configuration without clobbering the environment for your other projects.
pip install virtualenv virtualenv venv # create virtual environment source venv/bin/activate # start virtual environment pip install -r requirements.txt # install deps
Start the virtual environment
For all Django commands, if you're using a virtual environment, it must be initialized before you run the commands. Otherwise, the scripts won't be able to find the dependencies you downloaded to the virtual environment.
Before you run any of the below commands, make sure that you have activated the virtual environment:
Generate a secret key for the project
The secret key needs to be instantiated for any Django management commands.
DJANGO_SETTINGS_MODULE=tutorons.settings.dev \ python manage.py createsecretkey
When you run this command the first time, you will see this output. Don't worry, this is expected.
Exception when loading secret key ([Errno 2] No such file or directory: u'/Users/andrew/.tutorons/secret.key') Using placeholder secret key. Make sure that a secret key file is created at the location of SECRET_KEY_FILE (currently /Users/andrew/.tutorons/secret.key) by running: DJANGO_SETTINGS_MODULE=tutorons.settings.dev python manage.py createsecretkey If that's what you're doing right now, then kudos!
Set up the local database
The Tutorons server saves all queries made to it to a local database. This command sets up that database.
DJANGO_SETTINGS_MODULE=tutorons.settings.dev \ python manage.py migrate
Test the core
This command will run tests for the Tutorons core as well as all additional installed modules (in this case, the Python built-in module).
Start the server
To start the server, run the following command. Once it is
running, you can see it running and producing explanations
by going to
A port number can be provided as an argument to
rundevserver.sh if you want to run the server on a
Making your own Tutoron
This framework provides straightforward extension points for detecting code in web pages and building tooltip-based contextual explanations on the web. We encourage you to experiment with new Tutorons, for explaining new languages and creating novel types of explanations.
We created this how-to guide to show you how to build a Tutoron of your own! The minimum viable Tutoron can be created with a few commands. Following the full tutorial probably takes 1-2 hours and is recommended for anyone wanting to create and host a Tutoron.
- Create a new branch for doing your work:
git checkout -b <branchname>
- Do your local work and commit. All new features or bug fixes should have tests.
- Run the test suite to make sure everything still passes
- Push your branch
- Submit a pull request to merge into master (see here). Assign the pull request to someone else on the team who should verify the style and design choices of your code.
- Respond to any comments from reviewers
- Once your pull request is accepted, merge your pull request into master
- Check out the master branch and verify that all tests still pass
When installing dependencies, install them to a virtual environment instead of your global Python library. Here's how you can do this.
pip install virtualenv virtualenv venv # create a new virtual environment at folder "venv" source venv/bin/activate # start the virtual environment pip install -r requirements.txt
All pull requests should include an up-to-date version of the requirements. If you installed anything new, make sure to include a new requirements file in your commit:
pip freeze > requirements.txt
Don't install any dependencies that aren't released under a permissive open source license. This code has reworked so that it can be released under BSD so it can fit others' development needs. We don't want to change the conditions under which it is currently licensed.
Running unit tests
Before you commit, you need to make sure all existing tests are still running. The easiest way is to do the following from the main directory: