diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..1eb565d --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,52 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'gtk-blueprint-tool' +copyright = '2021, James Westman' +author = 'James Westman' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..093c2cb --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,245 @@ +======== +Examples +======== + + +Namespaces and libraries +------------------------ + +GTK declaration +~~~~~~~~~~~~~~~ + +.. code-block:: + + // Required in every blueprint file. Defines the major version + // of GTK the file is designed for. + using Gtk 4.0; + +Importing libraries +~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + // Import Adwaita 1. The name given here is the GIR namespace name, which + // might not match the library name or C prefix. + using Adw 1; + + +Objects +------- + +Defining objects with properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + Gtk.Box { + orientation: vertical; + + Gtk.Label { + label: "Hello, world!"; + } + } + +Referencing an object in code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + // Your code can reference the object by `my_window` + Gtk.Window my_window { + title: "My window"; + } + +Using classes defined by your app +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use a leading ``.`` to tell the compiler that the class is defined in your +app, not in the GIR, so it should skip validation. + +.. code-block:: + + .MyAppCustomWidget my_widget { + my-custom-property: 3.14; + } + + +Templates +--------- + +Defining a template +~~~~~~~~~~~~~~~~~~~ + +Many language bindings have a way to create subclasses that are defined both +in code and in the blueprint file. Check your language's documentation on +how to use this feature. + +In this example, we create a class called ``MyAppWindow`` that inherits from +``Gtk.ApplicationWindow``. + +.. code-block:: + + template MyAppWindow : Gtk.ApplicationWindow { + my-custom-property: 3.14; + } + + +Properties +---------- + +Translations +~~~~~~~~~~~~ + +Use ``_("...")`` to mark strings as translatable. You can put a comment for +translators on the line above. + +.. code-block:: + + Gtk.Label label { + /* Translators: This is the main text of the welcome screen */ + label: _("Hello, world!"); + } + +Referencing objects by ID +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + Gtk.Range range1 { + adjustment: my_adjustment; + } + Gtk.Range range2 { + adjustment: my_adjustment; + } + + Gtk.Adjustment my_adjustment { + } + +Defining object properties inline +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + Gtk.Range { + adjustment: Gtk.Adjustment my_adjustment { + value: 10; + }; + } + + Gtk.Range range1 { + // You can even still reference the object by ID + adjustment: my_adjustment; + } + +.. note:: + Note the semicolon after the closing brace of the ``Gtk.Adjustment``. It is + required. + +Bindings +~~~~~~~~ + +Use the ``bind`` keyword to bind a property to another object's property in +the same file. + +.. code-block:: + + Gtk.ProgressBar bar1 { + } + + Gtk.ProgressBar bar2 { + value: bind bar1.value; + } + +Binding Flags +~~~~~~~~~~~~~ + +Use the ``sync-create`` keyword to cause a bound property to be initialized +when the UI is first constructed. + +.. code-block:: + + Gtk.ProgressBar bar1 { + value: 10; + } + + Gtk.ProgressBar bar2 { + value: bind bar1.value sync-create; + } + + +Signals +------- + +Basic Usage +~~~~~~~~~~~ + +.. code-block:: + + Gtk.Button { + // on_button_clicked is defined in your application + clicked => on_button_clicked(); + } + +Flags +~~~~~ + +.. code-block:: + + Gtk.Button { + clicked => on_button_clicked() swapped; + } + + +CSS Styles +---------- + +Basic Usage +~~~~~~~~~~~ + +.. code-block:: + + Gtk.Label { + style "dim-label", "title"; + } + + +Menus +----- + +Basic Usage +~~~~~~~~~~~ + +.. code-block:: + + menu my_menu { + section { + label: _("File"); + item { + label: _("Open"); + action: "win.open"; + } + item { + label: _("Save"); + action: "win.save"; + } + submenu { + label: _("Save As"); + item { + label: _("PDF"); + action: "win.save_as_pdf"; + } + } + } + } + +Item Shorthand +~~~~~~~~~~~~~~ + +For menu items with only a label, action, and/or icon, you can define all three +on one line. The action and icon are optional. + +.. code-block:: + + menu { + item _("Copy") "app.copy" "copy-symbolic"; + } diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..bd2007b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,14 @@ +gtk-blueprint-tool +================== + +.. title:: Overview + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Contents: + + examples + + +gtk-blueprint-tool is a markup language and compiler for GTK user interfaces. diff --git a/docs/meson.build b/docs/meson.build new file mode 100644 index 0000000..9b76852 --- /dev/null +++ b/docs/meson.build @@ -0,0 +1,11 @@ +if get_option('docs') + +sphinx = find_program(['sphinx-build-3', 'sphinx-build'], required: true) + +custom_target('docs', + command: [sphinx, '-b', 'html', '-c', meson.current_source_dir(), meson.current_source_dir(), '@OUTPUT@'], + output: 'en', + build_by_default: true +) + +endif diff --git a/meson.build b/meson.build index 9aa0ee5..c96e662 100644 --- a/meson.build +++ b/meson.build @@ -2,6 +2,8 @@ project('gtk-blueprint-tool', version: '0.1.0', ) +subdir('docs') + prefix = get_option('prefix') libdir = join_paths(prefix, get_option('libdir')) diff --git a/meson_options.txt b/meson_options.txt new file mode 100644 index 0000000..c3c5661 --- /dev/null +++ b/meson_options.txt @@ -0,0 +1 @@ +option('docs', type: 'boolean', value: false)