docs: Add examples

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']

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";
+   }

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.

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

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'))
 

meson_options.txt

@@ -0,0 +1 @@
+option('docs', type: 'boolean', value: false)