### Run Tests with Tox Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/coding best practices.md Utilize the 'tox' Python testing package to run tests if installed. Tox automates environment setup and test execution. ```bash tox ``` -------------------------------- ### Install Coverage Tool Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/test suite - coverage testing.md Install the coverage tool using pip. This is the first step before running any coverage tests. ```bash pip3 install coverage ``` -------------------------------- ### Install Pre-commit Hooks Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Install pre-commit hooks to ensure code quality and consistency. These checks run automatically on commit. ```sh pip install pre-commit pre-commit install ``` -------------------------------- ### GTG Plugin Configuration File Example Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/plugin development guide.md This is an example of a .gtg-plugin configuration file. It specifies plugin metadata such as module, name, description, authors, version, dependencies, and D-Bus dependencies. ```ini [GTG Plugin] Module=example Name="Example plugin" Description="A plugin example" Authors="Paulo Cabido " Version=0.1 Dependencies=some_python_module Dbus-dependencies=org.gnome.Example:/org/gnome/Example Enabled=True ``` -------------------------------- ### Import Tasks from Flatpak Install Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Import GTG user data from a Flatpak installation into the development version. ```sh ./scripts/import_tasks_from_flatpak.sh ``` -------------------------------- ### Import Tasks from Local/System-wide Install Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Import GTG user data from a local or system-wide installation into the development version. ```sh ./scripts/import_tasks_from_local.sh ``` -------------------------------- ### Install Test Dependencies on Fedora Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Installs packages required to run the GTG test suite on Fedora. ```sh # On Fedora: sudo dnf install python3-pytest python3-pyflakes python3-spec python3-pycodestyle ``` -------------------------------- ### Install Export and Print Plugin Dependencies on Ubuntu/Debian Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Installs Python and LaTeX packages needed for the 'Export and print' plugin on Ubuntu/Debian. ```sh # On Ubuntu/Debian: sudo apt install python3-cheetah pdftk-java texlive-extra-utils texlive-latex-base ``` -------------------------------- ### Install Test Dependencies on Ubuntu/Debian Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Installs packages required to run the GTG test suite on Ubuntu/Debian. ```sh # On Ubuntu/Debian: sudo apt install python3-pytest python3-pyflakes python3-pep8 python3-pycodestyle python3-caldav ``` -------------------------------- ### Install GTG Dependencies on Fedora Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Installs the necessary packages for GTG development on Fedora using dnf. ```sh # On Fedora: sudo dnf install meson python3-cairo python3-gobject gtk3 itstool gettext python3-lxml libsecret gtksourceview4 ``` -------------------------------- ### Full GTG XML Data Example Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/file format.md This snippet shows a complete example of the GTG XML data file, including tag lists, saved searches, and tasks with subtasks, dates, and recurring settings. ```xml Learn How To Use Subtasks 7171ff82-119a-4933-8277-a8ef5ce6a3e2 46890bc2-c924-4146-8279-472099abc0b1 94669f60-2f8e-4b16-b87f-c1d46ade4536 a957c32a-6293-46f7-a305-1caccdfbe34c 2020-04-10T20:48:11 2020-04-10T20:37:02 2020-05-10T00:00:00 Monday An empty task 2020-04-10T20:48:11 2020-04-10T20:59:02 someday ``` -------------------------------- ### Pass Arguments Directly to GTG Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Arguments following `--` are passed directly to the `gtg` binary. This example shows how to display the `gtg` help message. ```sh ./launch.sh -- --help ``` -------------------------------- ### Coverage Testing Report Example Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/test suite - coverage testing.md This snippet displays a typical coverage testing report. It shows the number of statements, missed statements, and the calculated coverage percentage for each module. Use this to understand the code coverage of your project. ```text Name Stmts Miss Cover ---------------------------------------------------------------------------------- ../liblarch/liblarch_gtk/__init__ 281 34 88% ../liblarch/liblarch_gtk/treemodel 94 20 79% GTG/gtk/__init__ 8 0 100% GTG/gtk/backends_dialog/__init__ 118 6 95% GTG/gtk/backends_dialog/addpanel 93 0 100% GTG/gtk/backends_dialog/backendscombo 40 0 100% GTG/gtk/backends_dialog/backendstree 121 0 100% GTG/gtk/backends_dialog/configurepanel 103 7 93% GTG/gtk/browser/CellRendererTags 98 16 84% GTG/gtk/browser/__init__ 27 0 100% GTG/gtk/browser/browser 914 92 90% GTG/gtk/browser/modifytags_dialog 48 1 98% GTG/gtk/browser/tag_context_menu 33 0 100% GTG/gtk/browser/tag_editor 270 29 89% GTG/gtk/browser/treeview_factory 310 9 97% GTG/gtk/colors 47 23 51% GTG/gtk/delete_dialog 68 1 99% GTG/gtk/editor/__init__ 18 0 100% GTG/gtk/editor/calendar 95 6 94% GTG/gtk/editor/editor 377 45 88% GTG/gtk/editor/taskview 836 99 88% GTG/gtk/editor/taskviewserial 136 13 90% GTG/gtk/manager 158 19 88% GTG/gtk/plugins 174 42 76% GTG/gtk/preferences 155 12 92% GTG/gtk/tag_completion 60 2 97% ---------------------------------------------------------------------------------- TOTAL 4682 476 90% ``` -------------------------------- ### Install GTG Dependencies on Debian/Ubuntu Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Installs the necessary packages for GTG development on Debian/Ubuntu. Note: For Debian 10, a backported version of some packages might be required. ```sh # On Debian/Ubuntu: sudo apt install meson python3-gi-cairo python3-gi gir1.2-pango-1.0 gir1.2-gdkpixbuf-2.0 gir1.2-gtk-3.0 itstool gettext python3-lxml libgirepository1.0-dev libsecret-1.0 gir1.2-secret-1 ``` -------------------------------- ### View GTG User Manual with Yelp Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Access the GTG user manual through the Yelp help viewer. This command assumes Yelp is installed and GTG is accessible. ```sh yelp help:gtg ``` -------------------------------- ### Example Parser Error Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/contributing to the user manual.md This is an example of a parser error output from yelp-check, indicating a mismatch between opening and ending tags. ```Text gtg-translate.page:19: parser error : Opening and ending tag mismatch: app line 19 ``` -------------------------------- ### Update Translation Files Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Run this command to update the GTG translation template and existing translation files. Ensure dependencies like meson and gettext are installed. ```bash ninja -C .local_build gtg-pot gtg-update-po ``` -------------------------------- ### Get All Tasks JSON Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Retrieves a JSON string describing all tasks. This method is part of the org.gnome.GTG.Server interface. ```dbus ``` -------------------------------- ### Generate Graphical Profile with gprof2dot Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/profiling GTG for performance.md Converts cProfile data into a PNG image using gprof2dot and Graphviz for visualization. Ensure gprof2dot and Graphviz are installed. ```bash python gprof2dot.py -f pstats gtg.prof | dot -Tpng -o output.png ``` -------------------------------- ### Get All Tags JSON Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Retrieves a JSON string describing all tags. This method is part of the org.gnome.GTG.Server interface. ```dbus ``` -------------------------------- ### Commented Code Example with Explanation Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/coding best practices.md When commenting out code, always include a comment explaining why it was disabled, preferably with a TODO or FIXME tag and relevant issue tracker ID. This helps other developers understand the context and resolve the issue. ```python # FIXME: If x is None, it causes animate() to crash. But x should # never be None, so this *should* always work. I can't reproduce the # crash so can't tell what makes x None. Leaving it disabled for now # until someone can reproduce it and investigate. (LP: #12345) # # foo.animate(x) ``` -------------------------------- ### Mallard XML Namespaces and Page Structure Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/contributing to the user manual.md Declare necessary Mallard namespaces and define basic page attributes for a new guide page. This sets up the foundation for a new user manual page. ```xml ``` -------------------------------- ### Mallard XML Info Section Example Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/contributing to the user manual.md Structure the 'info' section of a Mallard XML page, including revision history, internal and external links, author/editor credits, and legal includes. This is essential for page metadata and referencing. ```xml Writer Name writer_email 2020 Editor Name editor_email 2020 ``` -------------------------------- ### Instantiate and Fill Datastore with Samples Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/core architecture.md Instantiate a new DataStore, fill it with sample data, and print its information. This is useful for testing and development within the console. ```python from GTG.core.datastore import DataStore ds = DataStore() ds.fill_with_samples(200) ds.print_info() ``` -------------------------------- ### View User Manual from Source Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Read the GTG documentation directly from the source code. This command should be run from the root directory of the GTG source code. ```sh yelp docs/user_manual/C/index.page ``` -------------------------------- ### Launch GTG with Specific Dataset Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Use the `-s` flag to specify a dataset to use, such as 'bryce' or 'screenshots'. If the dataset does not exist in the `tmp` folder, a new one will be created. ```sh ./launch.sh -s dataset ``` -------------------------------- ### Profile GTG with cProfile Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/profiling GTG for performance.md Launches GTG with cProfile enabled to generate a profiling data file. This is the first step before analyzing the performance. ```bash ./launch.sh -p 'python3 -m cProfile -o gtg.prof' ``` -------------------------------- ### Build HTML Documentation Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/contributing to the user manual.md Command to build an HTML version of the Mallard documentation files for external use. ```Shell yelp-build html *.page ``` -------------------------------- ### Launch GTG with Debugger Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Prepend `python3 -m pudb` to the launch command to run GTG under the PUDb debugger. ```sh ./launch.sh -p 'python3 -m pudb' ``` -------------------------------- ### Run All Linters with Make Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/coding best practices.md Execute all configured code quality and style checkers simultaneously using the Makefile. This provides a comprehensive check of the codebase. ```bash $ make lint=python3 ``` -------------------------------- ### Create New Task Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Creates a new task with optional tags. Returns the object path of the new task. The 'newtask' argument must be True. ```dbus ``` -------------------------------- ### org.gnome.GTG.Server.new_task Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Creates a new task with optional tags. ```APIDOC ## org.gnome.GTG.Server.new_task ### Description Creates a new Task, with some optional tags. The return value is the valid DBus Object Path of the new Task. If for any reason a new Task is not created, a DBus error will be raised. ### Method POST (or equivalent DBus call) ### Endpoint `/org/gnome/GTG/Server` ### Interface `org.gnome.GTG.Server` ### Parameters #### Request Body - **tags** (as) - Optional - An array of strings representing tags to associate with the new task. - **newtask** (b) - Required - This boolean argument must be `True`. ### Response #### Success Response - **task_object_path** (o) - The Object Path of the newly created task. ``` -------------------------------- ### Enable GTK Interactive Debugger Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Prepend `GTK_DEBUG=interactive` to the launch command to enable GTK's interactive debugger. ```sh GTK_DEBUG=interactive ./launch.sh ``` -------------------------------- ### Get List of Top Contributors Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/release process and checklist.md Retrieves a sorted list of contributors between two Git tags or commits, useful for updating the AUTHORS file. ```bash git shortlog -s -n previous_tag..new_tag_or_HEAD ``` -------------------------------- ### Coverage Configuration for Full Measurement Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/test suite - coverage testing.md Configure the .coveragerc file for full coverage measurement across the entire project, including external libraries like liblarch. ```ini [run] source = gtg GTG ../liblarch omit = run-tests GTG/tests/* ../liblarch/test* ``` -------------------------------- ### General Methods Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/plugin development guide.md Provides methods for interacting with the GTG UI elements like menus, toolbars, and task editors, as well as accessing core GTG objects. ```APIDOC ## General Methods ### add_menu_item(item) Adds a menu to the Plugin Menu in the menu bar of the task browser. **Parameters** * **item** (gio.MenuItem) - The menu item to be added. ### remove_menu_item(item) Removes a menu from the Plugin Menu in the menu bar of the task browser. **Parameters** * **item** (gio.MenuItem) - The menu item to be removed. ### add_toolbar_item(item) Adds a button to the task browser's toolbar. **Parameters** * **item** (gtk.ToolButton) - The toolbar button to be added. **Returns** * integer - The position of the item in the toolbar. ### remove_toolbar_item(item, n=None) Removes a toolbar button from the task browser's toolbar. **Parameters** * **item** (gtk.ToolButton) - The toolbar button to be removed. * **n** (integer, optional) - The position of the item to be removed. Useful for removing separator items. ### add_task_toolbar_item(item) Adds a button to the task editor's toolbar. **Parameters** * **item** (gtk.ToolButton) - The toolbar button to be added. ### add_widget_to_taskeditor(widget) Adds a widget to the bottom of the task editor dialog. **Parameters** * **widget** (gtk.Widget) - The widget to be added. ### get_requester() Retrieves the requester object. **Returns** * requester object ### requester_connect(action, func) Connects a function to a requester signal. **Parameters** * **action** (string) - The signal action. * **func** (function) - The function to connect to the signal. ### change_task_tree_store(treestore) Changes the TreeStore in the task browser's task view. **Parameters** * **treestore** (gtk.TreeStore) - The new TreeStore model. ### set_parent_window(child) Sets the plugin dialog as a child of its parent window. **Parameters** * **child** (dialog) - The dialog to be set as a child. ### get_taskview() Retrieves the task view object. **Returns** * task view object ### get_selected_task() Retrieves the selected task in the task view. **Returns** * selected task object ### get_config() Retrieves the configuration object. **Returns** * config object ``` -------------------------------- ### Run Test Suite Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/release process and checklist.md Executes the project's test suite to ensure code quality and stability. ```bash make check ``` -------------------------------- ### Run Unit Tests Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/coding best practices.md Execute the project's unit tests using the provided Makefile target. This ensures code changes do not introduce regressions. ```bash $ make check=python3 ./run-tests ........... ---------------------------------------------------------------------- Ran 11 tests in 0.063s OK ``` -------------------------------- ### Add and Commit Translation File Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Stage your translated `.po` file and commit it with a descriptive message indicating the language updated. ```bash git add po/.po git commit -m "Updated translation for " ``` -------------------------------- ### Create Tarball for Distribution Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/release process and checklist.md Generates a distributable tarball archive of the project. Assumes launch.sh has been run previously. ```bash ninja -C .local_build/ dist ``` -------------------------------- ### Create New Tag Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Creates a new tag with a specified name. Returns the object path of the new tag. ```dbus ``` -------------------------------- ### Launch GTG with Debugging Data Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/coding best practices.md Run GTG using a launch script that isolates data to a temporary directory. This is useful for manual testing without affecting real user data. ```bash ./launch.sh ``` -------------------------------- ### org.gnome.GTG.GtkUI Methods Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Provides methods for controlling the GTK-based user interface of the GTG application. ```APIDOC ## Interface: org.gnome.GTG.GtkUI ### Description Manages the visibility and interaction with the GTK user interface elements of the GTG application. ### Methods #### ShowBrowser ##### Description Shows the GTG browser window. ##### Method `ShowBrowser()` #### HideBrowser ##### Description Hides the GTG browser window. ##### Method `HideBrowser()` #### IconifyBrowser ##### Description Iconifies (minimizes) the GTG browser window. ##### Method `IconifyBrowser()` #### OpenTask ##### Description Opens a specific task in the GTG UI. ##### Method `OpenTask(o task)` ##### Parameters - **task** (o) - Input - An object path representing the task to open. #### OpenNewTask ##### Description Opens a new task creation dialog in the GTG UI. ##### Method `OpenNewTask()` ### Properties - **BrowserIsVisible** (b) - Read-only - Indicates whether the browser window is currently visible. ``` -------------------------------- ### org.freedesktop.DBus.Properties.List Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Lists properties of an interface, faster than GetAll. ```APIDOC ## org.freedesktop.DBus.Properties.List ### Description A faster alternative to `GetAll` that avoids a `Get` of every property. This is useful when some properties are computed instead of stored in variables. ### Method GET (or equivalent DBus call) ### Endpoint Any object path (e.g., `/org/gnome/GTG/Server`, `/org/gnome/GTG/Tag/[uuid]`, `/org/gnome/GTG/Task/[uuid]`) ### Interface `org.freedesktop.DBus.Properties` ### Parameters #### Query Parameters - **interface_name** (STRING) - Required - The name of the interface for which to list properties. ### Response #### Success Response - **props** (ARRAY) - An array of strings representing the names of the properties available in the specified interface. ``` -------------------------------- ### org.gnome.GTG.Server.get_tasks_json Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Retrieves a JSON string describing all tasks. ```APIDOC ## org.gnome.GTG.Server.get_tasks_json ### Description Retrieves a string that describes all tasks in JSON format. ### Method GET (or equivalent DBus call) ### Endpoint `/org/gnome/GTG/Server` ### Interface `org.gnome.GTG.Server` ### Parameters None ### Response #### Success Response - **tasks_json** (s) - A JSON string representing all tasks. ``` -------------------------------- ### Tag a Stable Release Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/release process and checklist.md Creates an annotated Git tag for a stable release. Use `git tag` to list existing tags and `git show` to view tag details. ```bash git tag -a vRELEASE_NUMBER ``` -------------------------------- ### Run Pre-commit Checks Locally Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Manually run all pre-commit checks across all files to ensure compliance before committing or creating a pull request. ```sh pre-commit run --all-files ``` -------------------------------- ### org.gnome.GTG.Server.new_tag Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Creates a new tag with a specified label. ```APIDOC ## org.gnome.GTG.Server.new_tag ### Description Creates a new Tag with the label `tagname`. The return value is the valid DBus Object Path of the new Tag. If for any reason a new Tag is not created, a DBus error will be raised. ### Method POST (or equivalent DBus call) ### Endpoint `/org/gnome/GTG/Server` ### Interface `org.gnome.GTG.Server` ### Parameters #### Request Body - **tagname** (s) - Required - The label for the new tag. ### Response #### Success Response - **tag_object_path** (o) - The Object Path of the newly created tag. ``` -------------------------------- ### Main Task List Generation Source: https://github.com/getting-things-gnome/gtg/blob/master/GTG/plugins/export/export_templates/template_textual.txt Iterates through a list of tasks and applies the `task_template` function to format each task for the textual output. This is the main entry point for generating the TODO list. ```Python ## ## ## TODO LIST: #for $task in $tasks: * $task_template($task, 3) #end for ## ## ``` -------------------------------- ### List DBus Properties Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Lists properties for a given interface. This is a faster alternative to GetAll. ```dbus org.freedesktop.DBus.Properties.List (in STRING interface_name, out ARRAY props); ``` -------------------------------- ### Clone GTG Development Repository Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Use this command to fetch the latest development code and navigate into the project directory. Later, use 'git pull --rebase' to update. ```sh git clone https://github.com/getting-things-gnome/gtg.git && cd gtg ``` -------------------------------- ### Tasklist Main Loop Jinja2 Source: https://github.com/getting-things-gnome/gtg/blob/master/GTG/plugins/export/export_templates/template_sexy.html Main loop to render all tasks using the task_template. ```jinja2 #for $task in $tasks: $task_template($task)#slurp #end for ``` -------------------------------- ### Module Copyright Header Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/coding best practices.md All Python modules must begin with a standardized copyright header that includes project information, copyright notice, and licensing details under the GNU General Public License. ```python # ----------------------------------------------------------------------------- # Getting Things GNOME! - a personal organizer for the GNOME desktop # Copyright (c) 2008-2022 - the GTG contributors # # This program is free software: you can redistribute it and/or modify it under # the terms of the GNU General Public License as published by the Free Software # Foundation, either version 3 of the License, or (at your option) any later # version. # # This program is distributed in the hope that it will be useful, but WITHOUT # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS # FOR A PARTICULAR PURPOSE. See the GNU General Public License for more # details. # # You should have received a copy of the GNU General Public License along with # this program. If not, see . # ----------------------------------------------------------------------------- ``` -------------------------------- ### Generate Flamegraph with flameprof Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/profiling GTG for performance.md Creates a flamegraph visualization from cProfile data, showing function call stacks over time. This helps in identifying hot spots in the application. ```bash flameprof -o gtg.svg gtg.prof ``` -------------------------------- ### Test Translation with Locale Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Launch GTG with a specific language and locale to test your translations. Replace `` with the desired language code (e.g., de_DE). ```bash LC_ALL=.UTF-8 LANGUAGE=.UTF-8 ./launch.sh ``` -------------------------------- ### org.gnome.GTG.Server.get_tags_json Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Retrieves a JSON string describing all tags. ```APIDOC ## org.gnome.GTG.Server.get_tags_json ### Description Retrieves a string that describes all tags in JSON format. ### Method GET (or equivalent DBus call) ### Endpoint `/org/gnome/GTG/Server` ### Interface `org.gnome.GTG.Server` ### Parameters None ### Response #### Success Response - **tags_json** (s) - A JSON string representing all tags. ``` -------------------------------- ### Basic GTG Plugin Python Structure Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/plugin development guide.md This Python code demonstrates the basic structure of a GTG plugin, including the `__init__`, `activate`, `onTaskOpened`, and `deactivate` methods. The `activate` method initializes the plugin, `onTaskOpened` handles task editor events, and `deactivate` reverses `activate`'s changes. ```python #!python class Example: def __init__(self): self.example = "This can initialize a class" def activate(self, plugin_api): print "the plugin is initialized" def onTaskOpened(self, plugin_api): print "a task was opened" def deactivate(self, plugin_api): print "the plugin was deactivated" ``` -------------------------------- ### Simple Task Template Rendering Source: https://github.com/getting-things-gnome/gtg/blob/master/GTG/plugins/export/export_templates/template_simple.html Renders a single task, including its title, tags, due date, text, and subtasks, using Jinja2-like syntax. This template is designed for basic task display. ```Jinja2 #for $task in $tasks $task_template($task) #end for #def task_template($task)* #if $task.has_title **$task.title** #if $task.has_tags (#slurp #for $tag in $task.tags: $get_colored_tag_markup($plugin_api.get_requester(), $tag, True) #slurp #end for )#slurp #end if #end if #if $task.has_due_date _Due: $task.due_date_ #end if #if $task.has_text $remove_html_tags($task.text) #end if #if $task.has_subtasks #for $subtask in $task.subtasks: $task_template($subtask) #end for #end if #end def ``` -------------------------------- ### Push Tags to Remote Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/release process and checklist.md Uploads all local tags to the remote repository. This action should be performed only after confirming tags are correct. ```bash git push --tags ``` -------------------------------- ### Generate Annotated HTML Coverage Report Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/test suite - coverage testing.md Create an annotated HTML report detailing missed lines for a more user-friendly presentation. This report can be viewed in a web browser. ```bash coverage html ``` -------------------------------- ### Create New Translation Branch Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Create and checkout a new branch for your translation work based on the master branch of the origin repository. ```bash git switch -c my-translation-branch origin/master ``` ```bash # If git switch isn't available, use: git branch my-translation-branch origin/master git checkout my-translation-branch ``` -------------------------------- ### org.gnome.GTG.Tag properties Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Read-write and read-only properties for GTG tags. ```APIDOC ## org.gnome.GTG.Tag Properties ### Description Properties associated with individual GTG tags. ### Interface `org.gnome.GTG.Tag` ### Properties - **Color** (s) - Read-write - The color associated with the tag. - **Name** (s) - Read-only - The name of the tag. - **Removable** (s) - Read-only - Indicates if the tag is removable. ``` -------------------------------- ### Insert Image in User Manual Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/contributing to the user manual.md Embed an image into a user manual page using figure tags, including a title and description. ```Mallard
Quick Add Entry
``` -------------------------------- ### Stage and Commit Changes Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/git workflow tips.md Stage specific files for commit and then commit them with a message. This saves your progress. ```bash git add changed_file_1_to_include changed_file_2_to_include_too git commit ``` -------------------------------- ### Fetch Latest Changes Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Update your local repository to fetch the latest changes from the upstream repository before creating a new translation branch. ```bash git fetch --all ``` -------------------------------- ### Run GTG Without Translations Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Use this command to launch GTG with the default C locale, effectively disabling all translations for testing purposes. ```bash LC_ALL=C.UTF-8 LANGUAGE=C.UTF-8 ./launch.sh ``` -------------------------------- ### Push Feature Branch to GitHub Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/git workflow tips.md Push your local feature branch to your fork on GitHub to make it available for a pull request. ```bash git push origin cool_new_feature ``` -------------------------------- ### Clean Build Directory Source: https://github.com/getting-things-gnome/gtg/blob/master/README.md Remove the `.local_build` directory to resolve issues with the meson build system. This action only removes build files and does not affect user data. ```sh rm -rf .local_build ``` -------------------------------- ### org.gnome.GTG.Server.list_tasks Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Retrieves the IDs of all tasks. ```APIDOC ## org.gnome.GTG.Server.list_tasks ### Description Retrieves the IDs of all Tasks in an array of strings. Unlike `get_tasks_json`, there is no information about hierarchy. ### Method GET (or equivalent DBus call) ### Endpoint `/org/gnome/GTG/Server` ### Interface `org.gnome.GTG.Server` ### Parameters None ### Response #### Success Response - **task_ids** (as) - An array of strings representing the IDs of all tasks. ``` -------------------------------- ### Task Template Jinja2 Source: https://github.com/getting-things-gnome/gtg/blob/master/GTG/plugins/export/export_templates/template_sexy.html Recursive template for rendering individual tasks and subtasks, including tags, title, text, and due date. ```jinja2 #def task_template($task, $is_subtask = '') #if $task.has_tags #for $tag in $task.tags: #end for #else #end if # #if $task.has_title $task.title #if $task.has_text $remove_html_tags($task.text) #end if #end if #slurp #if $task.has_due_date $task.due_date#slurp #end if #if $task.has_subtasks #for $subtask in $task.subtasks: $task_template($subtask, 'subtask') #end for #end if #end def ``` -------------------------------- ### Clone GTG Repository Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/git workflow tips.md Clone the GTG repository from GitHub to your local machine. Replace YOUR_GITHUB_USERNAME with your actual GitHub username. ```bash git clone https://github.com/YOUR_GITHUB_USERNAME/gtg.git ``` -------------------------------- ### Check Code with Pyflakes Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/coding best practices.md Use Pyflakes to identify simple Python mistakes and potential errors in the codebase. Run this command on the main GTG directory. ```bash $ pyflakes GTG/ ``` -------------------------------- ### Push Translation Branch to Fork Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Push your local translation branch to your forked repository to prepare for a pull/merge request. ```bash git push fork my-translation-branch ``` -------------------------------- ### Run Tests with Coverage Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/test suite - coverage testing.md Execute the GTG application with coverage enabled. This command runs the main GTG script with the debug flag and collects coverage data. ```bash coverage run gtg -d ``` -------------------------------- ### Add Fork Remote Repository Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Add the URL of your forked repository as a remote named 'fork' to push your translation branch. ```bash git remote add fork https://clone-url-of-your-forked-repo ``` -------------------------------- ### Coverage Configuration for GTK Part Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/test suite - coverage testing.md Configure the .coveragerc file to measure coverage specifically for the GTK components of the project. This includes specifying source directories and files to omit from the report. ```ini [run] source = gtg GTG/gtk ../liblarch/liblarch_gtk omit = run-tests GTG/tests/* ../liblarch/test* ``` -------------------------------- ### Table CSS Source: https://github.com/getting-things-gnome/gtg/blob/master/GTG/plugins/export/export_templates/template_sexy.html Basic styling for tables, including collapse and margin. ```css table { border-collapse: collapse; margin-bottom: 2em; } ``` -------------------------------- ### List Task IDs Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Retrieves the IDs of all tasks as an array of strings. Does not include hierarchy information. ```dbus ``` -------------------------------- ### Interactive Rebase onto Master Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/git workflow tips.md Perform an interactive rebase of your feature branch onto the master branch. Use with caution. ```bash git rebase -i master ``` -------------------------------- ### Update Translation Template Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/release process and checklist.md Updates the translation template file. Use the first command for standard updates and the second if a specific reason exists. ```bash ninja -C .local_build/ gtg-pot ``` ```bash ninja -C .local_build/ gtg-update-po ``` -------------------------------- ### org.gnome.GTG.Server.shutdown Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Shuts down the GTG daemon. ```APIDOC ## org.gnome.GTG.Server.shutdown ### Description Causes the daemon to save all of its data and terminate. This is identical to sending the `SIGQUIT` signal to the daemon process. ### Method POST (or equivalent DBus call) ### Endpoint `/org/gnome/GTG/Server` ### Interface `org.gnome.GTG.Server` ### Parameters None ### Response No specific response body is detailed, typically an empty success response or a DBus success signal. ``` -------------------------------- ### Validate User Manual Page Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/contributing to the user manual.md Use the yelp-check tool to validate a Mallard page file for syntax errors. Replace *.page with the specific file name. ```Shell yelp-check validate *.page ``` -------------------------------- ### org.gnome.GTG.Server.list_tags Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/DBus API v2.md Retrieves the IDs of all tags. ```APIDOC ## org.gnome.GTG.Server.list_tags ### Description Retrieves the IDs of all Tags in an array of strings. Unlike `get_tags_json`, there is no information about hierarchy. ### Method GET (or equivalent DBus call) ### Endpoint `/org/gnome/GTG/Server` ### Interface `org.gnome.GTG.Server` ### Parameters None ### Response #### Success Response - **tag_ids** (as) - An array of strings representing the IDs of all tags. ``` -------------------------------- ### Tag View Methods Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/plugin development guide.md Provides methods for customizing the tag popup menu in the tag view and retrieving the selected tag. ```APIDOC ## Tag View Methods ### add_menu_tagpopup(item) Adds a menu to the tag popup menu of the tag view. **Parameters** * **item** (menu) - The menu to be added to the tag popup menu. ### remove_menu_tagpopup(item) Removes a menu from the tag popup menu of the tag view. **Parameters** * **item** (menu) - The menu to be removed from the tag popup menu. ### get_tagpopup_tag() Retrieves the currently selected tag in the tag view. **Returns** * tag object - The selected tag. ``` -------------------------------- ### Analyze cProfile Results in IPython Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/profiling GTG for performance.md Parses the cProfile data file and prints the top 20 contributing functions sorted by cumulative time. Requires IPython and the pstats module. ```python import pstats p = pstats.Stats('gtg.prof') p.strip_dirs().sort_stats("cumulative").print_stats(20) ``` -------------------------------- ### Check Code Style with Pycodestyle Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/coding best practices.md Apply pycodestyle (formerly pep8) to check code against PEP 8 standards, with specific configurations for line length and ignored errors. This command finds all Python files and checks them. ```bash $ find . -name '*.py' -print0 | xargs -0 pycodestyle --repeat --max-line-length=100 --ignore=E128 ``` -------------------------------- ### Create a New Feature Branch Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/git workflow tips.md Create a new local branch for developing a feature. This isolates your work from the main codebase. ```bash git checkout -b cool_new_feature ``` -------------------------------- ### Generate Coverage Report Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/test suite - coverage testing.md Generate a text-based report of code coverage on the screen after running tests. This helps in quickly identifying which lines of code were executed. ```bash coverage report ``` -------------------------------- ### Reference Index Section Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/contributing to the user manual.md Use this Mallard syntax to link to a specific section within the index page from another page. ```Mallard ``` -------------------------------- ### Prepare Release Commit with Custom Dates Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/release process and checklist.md Sets custom author and committer dates for a Git commit, useful for preparing release commits in advance. Ensure GIT_COMMITTER_DATE is reused if rebasing. ```bash GIT_AUTHOR_DATE='the date and time' GIT_COMMITTER_DATE='the date and time' git commit ``` -------------------------------- ### Task Templating Logic Source: https://github.com/getting-things-gnome/gtg/blob/master/GTG/plugins/export/export_templates/template_textual.txt Recursively formats a task, including its title, tags, due date, text, and subtasks, into a textual representation. Handles indentation and line wrapping for task text. ```Python #def task_template($task, $space_num): #set spaces = " " * $space_num #if $task.has_title $html_unescape($task.title)#slurp #if $task.has_tags (#slurp #for $tag in $task.tags: $tag #slurp #end for )#slurp #if $task.has_due_date due: $task.due_date #end if #end if #end if #if $task.has_text #set $text =$remove_html_tags($task.text) #set $text = $html_unescape($text) ## ## Formatting the text to be shorter than 80 chars ## #while $len($text)>0: #set $text = $text.lstrip('\n') #if $len($text)<=80: #set next_len = $len($text) #else: #set next_len = max([80 - $space_num,50]) #end if #set $next_cr = $text.find('\n') #if $next_cr < $next_len and $next_cr >0: $spaces#slurp $text[:$next_cr] #set $text = $text[$next_cr:] #else: $spaces#slurp $text[:$next_len] #set $text = $text[$next_len:] #end if #end while ## ## ## #end if ## #if $task.has_subtasks #for $subtask in $task.subtasks: $spaces - $task_template($subtask, $space_num + 2) #end for #end if #end def ``` -------------------------------- ### Status Report Generation Source: https://github.com/getting-things-gnome/gtg/blob/master/GTG/plugins/export/export_templates/template_statusrpt.txt Iterates through a list of tasks to generate a status report using the task_template function. Each task is formatted and indented. ```Python ## ## Status Report: #for $task in $tasks: * $task_template($task, 3) #end for ## ## ``` -------------------------------- ### Task Related Methods Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/plugin development guide.md Enables plugins to retrieve, manipulate, and add tags to tasks within the GTG system. ```APIDOC ## Task Related Methods ### get_all_tasks() Retrieves a list of all existing tasks. **Returns** * list - A list containing all tasks. ### get_task(tid=None) Retrieves the current task or a specific task by its ID. Primarily used with the task editor's `onTaskOpened` method. **Parameters** * **tid** (integer, optional) - The ID of the task to retrieve. **Returns** * task object - The current or specified task. ### get_task_title(tid=None) Retrieves the title of the current task or a specific task by its ID. Primarily used with the task editor's `onTaskOpened` method. **Parameters** * **tid** (integer, optional) - The ID of the task to retrieve the title from. **Returns** * string - The title of the current or specified task. ### insert_tag(tag) Inserts a tag into the current task's text view. This method is intended for use with the `onTaskOpened` method. **Parameters** * **tag** (string) - The name of the tag to insert (without the '@' prefix). ### add_tag(tag, tid=None) Adds a tag directly to a task. Primarily used with the task editor's `onTaskOpened` method. **Parameters** * **tag** (string) - The name of the tag to add (without the '@' prefix). * **tid** (integer, optional) - The ID of the task to add the tag to. ### add_tag_attribute(attrib_name, attrib_value) Adds an attribute to a tag in the current task. This method is intended for use with the `onTaskOpened` method. **Parameters** * **attrib_name** (string) - The name of the attribute. * **attrib_value** (string) - The value of the attribute. ### get_tags(tid=None) Retrieves all tags associated with the current task or a specific task by its ID. Primarily used with the task editor's `onTaskOpened` method. **Parameters** * **tid** (integer, optional) - The ID of the task to retrieve tags from. **Returns** * list - A list of tags associated with the task. ### get_textview() Retrieves the text view object of the task editor. This method is intended for use with the `onTaskOpened` method. **Returns** * gtk.TextView object - The task editor's text view. ``` -------------------------------- ### Trigger Error Handler Dialog (Recoverable) Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Activate the developer console plugin and paste this Python code to display a recoverable error dialog for testing. ```python import GTG.gtk.errorhandler; GTG.gtk.errorhandler.do_error_dialog(Exception("Exception description"), "This is English only because it is for developers", True) ``` -------------------------------- ### Tasklist Body CSS Source: https://github.com/getting-things-gnome/gtg/blob/master/GTG/plugins/export/export_templates/template_sexy.html Defines basic styling for the tasklist body, including font and padding. ```css Tasklist body { font-family: 'Droid Sans', Calibri, 'Lucida Grande' Helvetica, sans-serif; padding: 0 0.5em 2em 0.5em; } ``` -------------------------------- ### Trigger Error Handler Dialog (Non-Recoverable) Source: https://github.com/getting-things-gnome/gtg/blob/master/docs/contributors/translating.md Use this Python code in the developer console to trigger a non-recoverable error dialog, typically used for critical startup errors. ```python import GTG.gtk.errorhandler; GTG.gtk.errorhandler.do_error_dialog(Exception("Exception description"), "This is English only because it is for developers", False) ```