QTutor

QTutor allows to run step-by-step semi-interactive lessons to learn QGIS and its plugins.

QTutor inspired and based on the awesome work of Victor Olaya on the Lessons plugin which was never published for wide usage.

Installation

Plugin published in my repository.

Usage

Once installed and enabled, QTutor creates a submenu in the QGIS "Plugins" menu and also adds a button to the "Plugins" toolbar. If you don't see its icon, please make sure that the "Plugins" toolbar is enabled.

Clicking on the plugin's button or menu item will open plugin's main dialog — QTutor library.

QTutor library

On the left side of the libarary dialog there is a tree with all available lessons. Double-click on the group to expand/collapse its content. Click on the lesson item to see its description in the right side of the dialog.

To install lessons from the lessons package click on the "Add lessons…" button. You will be prompted for lessons package location and after installation new lessons will be added to the tree. To remove lesson select it in the tree and click on the "Remove lesson(s)" button.

To start lesson press "Start lesson" button. QTutor library will be closed and QTutor dock will be added to the right side of the QGIS main window.

QTutor dock

QTutor dock cosists of two parts: on the top there is a list of the all lessons step with current step highlighted, below there is a detailed step description, giving you all information needed to finish current step. To complete lesson you need to perform all its steps.

To finish step read its description and perfom all described actions, then press "Next" button. If "Execute" button is enabled and you have difficulties with completing step, click on it and plugin will peform all step actions for you. Use this functionality only if you are really stuck with instructions.

Some steps, mainly these which ask you to select menu entry, will be completed in an automated way immediately after you perform action (e.g. clicked on the menu entry), so there is no need to press "Next" button.

When "Next" button pressed plugin will check if all instruction are completed and depending on this will move you to the next lesson step or will show a warning and ask to complete current step.

To restart lesson use "Restart" button, "Quit" button can be used to exit current lesson at any time.

When you complete the lesson an information dialog will be shown with optional list of the recommened lessons, which may complement topic of the just finished lesson.

Lesson finished

Closing this dialog will close lesson dock and return you to the QTutor library and clicking on the one of the recommended lesson will start that lesson.

Plugin settings

To configure QTutor open QGIS options from the menu "Settings → Options" and go to the "QTutor" tab.

QTutor settings

In the "QTutor paths" group you can manage (add/remove/reorder) directories used for lessons. By default there is only one directory, but you can add more, for example a shared network drive. The first directory in the list will be a default lessons location: all lessons installed by user will be saved into that directory.

Below there is a checkbox "Don't load built-in (demo) lessons", as the name suggest it allows to hide built-in lessons from the QTutor library.

Creating lessons

Each QTutor lesson is a directory with several files and optional locale-specific subdirectories. The main lesson file is a YAML file called lesson.yaml, which should be placed in the directory root. This file contains lesson metadata and describes all its steps.

The optional functions.py file also should be placed in the directory root. This file contains custom Python functions used by the lesson to perform some preparations, check steps completion and provider automatic steps execution.

If lesson needs some data, for example, layers and/or complete projects, they should be placed into the data subdirectory. If data subdirectory contains project.qgsor project.qgz project file, this file will be automatically loaded as the first lesson step.

Packaging lessons

To distribute lessons you need to prepare package. Lessons package is a ZIP file with one or more lessons, which will be unzipped into default lessons directory. So lessons should have their own directory inside ZIP archive to not interfere with other lessons.

Adding lessons to the plugin

Also lessons can be a part of the QGIS Python plugin and give users brief introduction into plugin features.

Create lesson(s) as usual and place them into separate directory inside plugin source tree. Then in the main plugin file add following snippet in the end of the initGui() method, after all UI initialization (here we assume that lessons located in the lessons subdirectory of the plugin directory and pluginPath variable contains full path to the plugin's directory)


try
    from qtutor import lessonsRegistry
    lessonsRegistry.addLessonsDirectory(os.path.join(pluginPath, 'lessons'))
except:
    pass

And similar code snipped to the end of the unload() method


try
    from qtutor import lessonsRegistry
    lessonsRegistry.removeLessonsDirectory(os.path.join(pluginPath, 'lessons'))
except:
    pass

Reporting bugs

Please report bugs via bugtracker.