From f4a9a668c2b5191f01c469488e31db5048c31dc6 Mon Sep 17 00:00:00 2001 From: Andy Meneely Date: Wed, 4 Jan 2017 15:31:29 -0500 Subject: [PATCH] docs: cleanup and warning fixes --- docs/config.rst | 2 +- docs/dsl/data_frame.rst | 2 +- .../getting-started/part_0_learning_ruby.rst | 4 ++- .../getting-started/part_1_zero_to_game.rst | 12 ++++++-- docs/help.rst | 29 +++++++++++-------- docs/install.rst | 12 ++++++-- docs/text_feature.rst | 10 +++---- samples/project/Rakefile | 1 + 8 files changed, 46 insertions(+), 26 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index 28dd65f..ceb0c2a 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -113,7 +113,7 @@ For debugging/sanity purposes, if you want to make sure your configuration optio These are read-only - you will not be able to change these. -Squib.configure sets options programmatically +Set options programmatically --------------------------------------------- You can also use :doc:`/dsl/configure` to override anything in the config file. Use it like this: diff --git a/docs/dsl/data_frame.rst b/docs/dsl/data_frame.rst index 078293e..12729fb 100644 --- a/docs/dsl/data_frame.rst +++ b/docs/dsl/data_frame.rst @@ -39,7 +39,7 @@ Returns ``true`` if there is column ``name``. #row(i) ------- -Returns a hash of values across all columns in the ``i``th row of the dataframe. Represents a single card. +Returns a hash of values across all columns in the i-th row of the dataframe. Represents a single card. #nrows ------ diff --git a/docs/guides/getting-started/part_0_learning_ruby.rst b/docs/guides/getting-started/part_0_learning_ruby.rst index affdb5f..11e5019 100644 --- a/docs/guides/getting-started/part_0_learning_ruby.rst +++ b/docs/guides/getting-started/part_0_learning_ruby.rst @@ -82,7 +82,9 @@ Executing Ruby is usually done through the command line. Depending on your oper * On Windows, there's the Command Prompt (Windows Key, `cmd`). It's a little janky, but it'll do. I've developed Squib primarily in Windows using the Command Prompt. * If you're on Linux/BSD/etc, you undoubtedly know what the command line is. -For example:: +For example: + +.. code-block:: none $ cd c:\game-prototypes $ gem install squib 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 7802bad..6fa7986 100644 --- a/docs/guides/getting-started/part_1_zero_to_game.rst +++ b/docs/guides/getting-started/part_1_zero_to_game.rst @@ -19,7 +19,9 @@ But! We also want to get the *second* (and third and fourth and fifth...) versio Get Installed and Set Up ----------------------------- -The ordinary installation is like most Ruby gems:: +The ordinary installation is like most Ruby gems: + +.. code-block:: none $ gem install squib @@ -31,7 +33,9 @@ Our Idea: Familiar Fights ------------------------- Let's start with an idea for a game: Familiar Fights. Let's say we want to have players fight each other based on collecting cards that represent their familiars, each with different abilities. We'll have two factions: drones and humans. Each card will have some artwork in it, and some text describing their powers. -First thing: the title. It stinks, I know. It's gonna change. So instead of naming the directory after our game and getting married to our bad idea, let's give our game a code name. I like to use animal names, so let's go with Arctic Lemming:: +First thing: the title. It stinks, I know. It's gonna change. So instead of naming the directory after our game and getting married to our bad idea, let's give our game a code name. I like to use animal names, so let's go with Arctic Lemming: + +.. code-block:: none $ squib new arctic-lemming $ cd arctic-lemming @@ -139,7 +143,9 @@ So technically, these two lines are equivalent:: Ok back to the game. We COULD just put our data into literal arrays. But that's considered bad programming practice (called *hardcoding*, where you put data directly into your code). Instead, let's make use of our CSV data file. -What the ``csv`` command does here is read in our file and create a hash of arrays. Each array is a column in the table, and the header to the colum is the key to the hash. To see this in action, check it out on Ruby's interactive shell (``irb``):: +What the ``csv`` command does here is read in our file and create a hash of arrays. Each array is a column in the table, and the header to the colum is the key to the hash. To see this in action, check it out on Ruby's interactive shell (``irb``): + +.. code-block:: none $ irb 2.1.2 :001 > require 'squib' diff --git a/docs/help.rst b/docs/help.rst index b1c246b..937921b 100644 --- a/docs/help.rst +++ b/docs/help.rst @@ -1,9 +1,14 @@ Get Help and Give Help ====================== +Show Your Pride +--------------- + .. raw:: html - On BoardGameGeek.com? Show your Squib pride by getting the microbadge and joining our guild! + On BoardGameGeek.com? Show your Squib pride by getting the microbadge and joining our guild! + +We would also love to hear about the games you make with Squib! Get Help -------- @@ -33,13 +38,6 @@ You can also watch the project on GitHub, which means you get notified when new Help by Beta Testing -------------------- -.. Testers needed!! If you want to test new features as I develop them, or make sure I didn't break your code, you can always point your Gemfile to the repository and follow what I'm doing there. Your Gemfile specification looks like this:: -.. -.. gem 'squib', git: 'git://github.com/andymeneely/squib', branch: 'dev' -.. -.. * The ``dev`` branch is where I am working on features in-process. I have not done much regression testing at this point, but would love testing feedback nonetheless. -.. * The ``master`` branch is where I consider features and bug that are done and tested, but not released yet. - Squib is a small operation. And programming is hard. So we need testers! In particular, I could use help from people to do the following: * Test out new features as I write them @@ -54,7 +52,9 @@ Beta: Using Pre-Builds The preferred way of doing beta testing is by to get Squib directly from my GitHub repository. Bundler makes this easy. -If you are just starting out you'll need to install bundler:: +If you are just starting out you'll need to install bundler: + +.. code-block:: none $ gem install bundler @@ -64,12 +64,15 @@ Then, in the root of your Squib project, create a file called `Gemfile` (capital gem 'squib', git: 'git://github.com/andymeneely/squib', branch: 'master' -Then run:: +Then run: + +.. code-block:: none $ bundle install -Your output will look something like this:: +Your output will look something like this: +.. code-block:: none Fetching git://github.com/andymeneely/squib Fetching gem metadata from https://rubygems.org/......... @@ -100,7 +103,9 @@ To double-check that you're using the test version of Squib, puts this in your c # Rest of your Squib code... -When you run your code, say ``deck.rb``, you'll need to put ``bundle exec`` in front of it. Otherwise Ruby will just go with full releases (e.g. ``0.8`` instead of pre-releases, e.g. ``0.9a``). That would look like this:: +When you run your code, say ``deck.rb``, you'll need to put ``bundle exec`` in front of it. Otherwise Ruby will just go with full releases (e.g. ``0.8`` instead of pre-releases, e.g. ``0.9a``). That would look like this: + +.. code-block:: none $ bundle exec ruby deck.rb diff --git a/docs/install.rst b/docs/install.rst index 98b3eaf..a1f242e 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -23,7 +23,9 @@ If you're using `Bundler `_, add this line to your applicatio gem 'squib' -And then execute:: +And then execute: + +.. code-block:: none $ bundle install @@ -36,11 +38,15 @@ At this time we consider Squib to be still in initial development, so we are not To keep track of when new Squib releases come out, you can watch the `BoardGameGeek thread `_ or follow the RSS feed for Squib on its `RubyGems page `_. -In RubyGems, the command looks like this:: +In RubyGems, the command looks like this: + +.. code-block:: none $ gem up squib -As a quirk of Ruby/RubyGems, sometimes older versions of gems get caught in caches. You can see which versions of Squib are installed and clean them up, use ``gem list`` and ``gem cleanup``:: +As a quirk of Ruby/RubyGems, sometimes older versions of gems get caught in caches. You can see which versions of Squib are installed and clean them up, use ``gem list`` and ``gem cleanup``: + +.. code-block:: none $ gem list squib diff --git a/docs/text_feature.rst b/docs/text_feature.rst index 08a341f..b69d754 100644 --- a/docs/text_feature.rst +++ b/docs/text_feature.rst @@ -87,14 +87,14 @@ Sample: _text.rb Sample: text_options.rb ^^^^^^^^^^^^^^^^^^^^^^^ -.. literalinclude:: ../samples/text_options.rb +.. literalinclude:: ../samples/text/_text_options.rb :language: ruby :linenos: Sample: embed_text.rb ^^^^^^^^^^^^^^^^^^^^^ -.. literalinclude:: ../samples/embed_text.rb +.. literalinclude:: ../samples/text/_embed_text.rb :language: ruby :linenos: @@ -102,14 +102,14 @@ Sample: embed_text.rb Sample: config_text_markup.rb ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. literalinclude:: ../samples/config_text_markup.rb +.. literalinclude:: ../samples/config/config_text_markup.rb :language: ruby :linenos: -.. literalinclude:: ../samples/config_text_markup.yml +.. literalinclude:: ../samples/config/config_text_markup.yml :language: ruby :linenos: -.. literalinclude:: ../samples/config_disable_quotes.yml +.. literalinclude:: ../samples/config/config_disable_quotes.yml :language: ruby :linenos: diff --git a/samples/project/Rakefile b/samples/project/Rakefile index f2d41eb..eb9da1e 100644 --- a/samples/project/Rakefile +++ b/samples/project/Rakefile @@ -1,3 +1,4 @@ +# This is a sample Rakefile require 'squib' desc 'Build all decks black-and-white'