From f41c1e806d283c1d28874e2e22fa4a4e422cb105 Mon Sep 17 00:00:00 2001 From: Andy Meneely Date: Sat, 5 Nov 2016 00:01:40 -0400 Subject: [PATCH] docs: fill out hello world dissected --- CHANGELOG.md | 1 + .../getting-started/part_1_zero_to_game.rst | 7 -- .../getting-started/part_2_iconography.rst | 3 + docs/guides/hello_world.rst | 67 +++++++++++++++++-- 4 files changed, 67 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fee06cf..de7ba74 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ Features: Docs: * Wrote out documentation for [Squib and GameIcons](http://squib.readthedocs.io/en/latest/guides/game_icons.html) +* Wrote out documentation for Hello World! Dissected Chores: * Bumped dependency roo to 2.5.1. Nothing that affects Squib users (probably). diff --git a/docs/guides/getting-started/part_1_zero_to_game.rst b/docs/guides/getting-started/part_1_zero_to_game.rst index 1e6fa12..4ce0275 100644 --- a/docs/guides/getting-started/part_1_zero_to_game.rst +++ b/docs/guides/getting-started/part_1_zero_to_game.rst @@ -1,13 +1,6 @@ The Squib Way pt 1: Zero to Game ================================= -.. warning:: - - Conversion from markdown not finished yet - -Prototyping with Squib ----------------------- - Squib is all about being able to change your mind quickly. Change data, change layout, change artwork, change text. But where do we start? What do we work on first? The key to prototyping tabletop games is *playtesting*. At the table. With humans. Printed components. That means that we need to get our idea out of our brains and onto pieces of paper as fast as possible. diff --git a/docs/guides/getting-started/part_2_iconography.rst b/docs/guides/getting-started/part_2_iconography.rst index c75e561..0e09078 100644 --- a/docs/guides/getting-started/part_2_iconography.rst +++ b/docs/guides/getting-started/part_2_iconography.rst @@ -144,6 +144,9 @@ Icons for Some, But Not All, Cards to be written +* Method: filenames in Excel +* Method: filenames in Layout + Method 1: Ruby Array#map ------------------------ diff --git a/docs/guides/hello_world.rst b/docs/guides/hello_world.rst index b651f0f..a0af121 100644 --- a/docs/guides/hello_world.rst +++ b/docs/guides/hello_world.rst @@ -1,6 +1,65 @@ -Hello, World! -============= +Hello, World! Dissected +======================= -.. note:: +After seeing Squib's `landing page `_, your might find it helpful to dissect what's really going on in each line of code of a basic Squib snippet. - Under construction +.. code-block:: ruby + :linenos: + + require 'squib' + + Squib::Deck.new width: 825, height: 1125, cards: 2 do + background color: 'pink' + rect + text str: ['Hello', 'World!'] + save_png prefix: 'hello_' + end + +Let’s dissect this: + +* Line 1: this code will bring in the Squib library for us to use. Keep this at the top. +* Line 2: By convention, we put a blank line between our require statements and the rest of our code +* Line 3: Define a new deck of cards. Just 2 cards. 825 pixels wide etc. Squib also supports :doc:`/units` if you prefer to specify something like ``'2.75in'``. +* Line 4: Set the background to pink. Colors can be in various notations, and supports linear and radial graidents - see :doc:`/colors`. +* Line 5: Draw a rectangle around the edge of each card. Note that this has no arguments, because :doc:`/parameters`. The defaults can be found in the DSL reference for the :doc:`/dsl/rect` method. +* Line 6: Put some text in upper-left the corner of the card, using the default font, etc. See the :doc:`/dsl/text` DSL method for more options. The first card will have ``'Hello'`` and the second card will have ``'World'`` because :doc:`/arrays`. +* Line 7: Save our card out to a png files called ``hello_00.png`` and ``hello_01.png`` saved in the ``_output`` folder. + +Dissection of "Even Bigger..." +------------------------------ + +On Squib's `landing page `_ we end with a pretty complex example. It's compact and designed to show how much you can get done with a little bit of code. Here's a dissection of that. + +.. code-block:: ruby + :linenos: + + require 'squib' + + Squib::Deck.new(cards: 4, layout: %w(hand.yml even-bigger.yml)) do + background color: '#230602' + deck = xlsx file: 'even-bigger.xlsx' + svg file: deck['Art'], layout: 'Art' + + %w(Title Description Snark).each do |key| + text str: deck[key], layout: key + end + + %w(Attack Defend Health).each do |key| + svg file: "#{key.downcase}.svg", layout: "#{key}Icon" + text str: deck[key], layout: key + end + + save_png prefix: 'even_bigger_' + showcase file: 'showcase.png', fill_color: '#0000' + hand file: 'hand.png', trim: 37.5, trim_radius: 25, fill_color: '#0000' + end + +* Line 3: Make 4 cards. Use two layouts: the built-in hand.yml (see :doc:`/layouts`) and then our own layout. The layouts get merged, with our own `even-bigger.yml` overriding ``hand.yml`` whenever they collide. +* Line 5: Read some data from an Excel file, which amounts to a column-based hash of arrays, so that each element of an array corresponds to a specific data point to a given card. For example, ``3`` in the ``'Attack'`` column will be put on the second card. +* Line 6: Using the Excel data cell for the filename, we can customize a different icon for every card. But, every SVG in this command will be styled according to the ``Art`` entry in our layout (i.e. in ``even-bigger.yml``) +* Line 8: Iterate over an array of strings, namely, ``'Title'``, ``'Description'``, and ``'Snark'``. +* Line 9: Draw text for the (Title, Description, or Snark), using *their* styling rules in our layout. +* Line 13: Using `Ruby String interpolation `_, lookup the appropriate icon (e.g. ``'attack.svg'``), converted to lowercase letters, and then using the Icon layout of that for styling (e.g. ``'AttackIcon'`` or ``'DefendIcon'``) +* Line 17: Render every card to individual PNG files +* Line 18: Render a "showcase" of cards, using a perspective-reflect effect. See :doc:`/dsl/showcase` method. +* Line 19: Render a "hand" of cards (spread over a circle). See :doc:`/dsl/hand` method.