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.
Plugin published in my repository.
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.
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.
QTutor shipped with two demo lessons, they are very simple and their main goal is to demonstrate plugin features. Other lessons should be installed separately or as part of the other plugins (of course, if plugin's author have created them).
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.
Built-in demo lessons can not be removed. However you can hide them from the tree, check Plugin settings section below for more information. Also it is not possible to remove lessons which are part of the another plugin.
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 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.
Lesson progress is not saved, if you have exited in the middle of the lesson, you will need to start from scratch next 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.
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.
To configure QTutor open QGIS options from the menu "Settings → Options" and go to the "QTutor" tab.
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.
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.
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.qgz project file, this file will be automatically loaded as the first lesson step.
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
try from qtutor import lessonsRegistry lessonsRegistry.removeLessonsDirectory(os.path.join(pluginPath, 'lessons')) except: pass
Please report bugs via bugtracker.