Generating Documentation using Sphinx

Recently I’ve been working on a python project and decided to use the highly-praised Sphinx package to generate useful and beautiful documentation for it. Unfortunately I found Sphinx’s own documentation to be a somewhat lacking – which is kind of ironic if you ask me. Anyway, here are the steps I found to go from “A dirty pile of python code with no documentation at all” to “A dirty pile of python code with beatifully formated sphinx-generated documentation.”

1. Put sphinx-readable documentation into your code.

This is fairly straightforward.

Under the declaration for each module, class, and function put a few lines of documentation code. With Sphinx you have two options (AFAIK) – google styled docstrings according to Google’s Python Styling Guide or sphinx styled docstrings. The sphinx documentation gives a good run-down of these styles.

I went with the Google-styled documentation because it’s a lot more readable within the code itself, but I do miss some of the more readable styling from the generated documentation. So it’s up to you to figure out what you think is most important for your project.

2. Install sphinx

I used pip.

sudo pip install sphinx

It worked. It was awesome.

3. Run sphinx-quickstart from the root folder for documentation

Sphinx-quickstart is an interactive prompt that generates most of the files you will need for sphinx documentation. It will prompt you for your project name, your name, the version, etc.

I followed the sphinx documentation on this one. I did it twice, opting both to generate a Makefile and not. The Makefile seemed pretty useful.

4. Run sphinx-apidoc on my package folder

This is the first required step that I couldn’t really find much info on in Sphinx’s official documentation.

Sphinx-apidoc runs through your python files and generates a .rst file for each of the modules included in your project. These files are what tells sphinx to what it needs to include in the final html or pdf documentation.

The sphinx-apidoc command requires an input directory – i.e. the directory with your source code, and an output directory – which should be the source directory generated by sphinx-quickstart. Like this:

sphinx-apidoc -o <path-to-sphinx-source> <path-to-python-files>

4. Add the generated .rst files to index.rst

When you ran sphinx-quickstart in step 3 it should have generated an index.rst file in the source directory. This file defines what the index of your documentation tree looks like. After you generated additional .rst files for your projects modules, you need to add them to the index.rst file so that sphinx will link to the documentation you included in your source code.

Initially your index.rst file will look like this:

your-project-name
=====================================

Contents:

.. toctree::
:maxdepth: 2


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

You need to add the files generated from sphinx-apidoc in the contents section. Do not include the .rst extention

your-project-name
=====================================

Contents:

.. toctree::
:maxdepth: 2
name-of-file1-generated-by-sphinx-apidoc
name-of-file2-generated-by-sphinx-apidoc
...

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

5. Add your source code directory to your path in conf.py

Lastly you need to make sure sphinx can find your soure code. To do this you need to include them in sphinx’s path. This can be done by adding a line to the conf.py file in sphinx’s source directory with the relative path.

import sys
import os

# 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.
sys.path.insert(0, os.path.abspath('../../.'))

6. Run sphinx-build or make

If everything is setup correctly you should be rewarded with a set of well-formatted html files documenting your code.

Posted in Design, Public | Tagged , , , | Leave a comment

Three Kings

3Kings

 

I made Three Kings for the 2013 Holiday Game Jam by Glitch City. It’s an interactive exploration of one of my favorite Christmas carols: “We Three Kings of Orient Are.”

I’ve worked on it since then, cleaning up the bugs and making it a little less “game-jamy” The levels ended up being a little too long, and cinematic scenes are still a little rough, but overall I’m very happy with how the game turned out.

The music for this was done by the ever amazing Angus McKay.

Download Three Kings for Mac and PC

Posted in Design | Leave a comment

Psychology Books for Game Designers

A few months ago I saw a question on reddit (in the /r/gamedesign subreddit) asking about useful books on psychology for game designers. At the time I had just finished a book on Jung and had been thinking a lot about how idea of the collective unconscious can be used in game design – so I had a pretty good response ready.

I’m reposting it here for posterity:

First off, read anything by Carl Jung. His theories on archetypes and the collective unconscious form the groundwork upon which not only games, but the entire modern entertainment industry are built.

Basically Jung argues that there is a collective set of symbols and ideas that all humans, regardless of culture or upbringing will respond to. Understanding these symbols, and building your game around them – either as mechanics or story – allows you to influence how the player will respond.

Jung: A Very Short Introduction is a pretty easy way to get started. After you read that I’d suggest getting into the meat of Jung’s own words with The Portable Jung (coincidentally edited by Joseph Campbell)

And with that, you should also read The Hero with a Thousand Faces by Joseph Campbell. He takes Jung’s ideas, and shows the specific symbols used in the Hero’s Journey – one of the most common story types. People talk about the Hero’s Journey all the time – but it’s a really important concept to understand if you’re doing any sort of creative works. Here are two quick video primers on it:

A more serious one: Ted Ed: What Makes a Hero

A more awesome one: Glove and Boots: The Hero’s Journey :)

If you want to go further on the narrative route I’d also suggest The Seven Basic Plots by Christopher Booker. He takes the Hero’s Journey and shows how it is just one of several different plot archetypes, all of which have their own internal path, rules, and idiosyncrasies.

Now, in case you’re thinking “Why are you sharing these books about narrative with me? Games are not stories!” remember that people have been responding to stories for all time – and good storytellers are masters at making people feel the desired emotion at the desired time.

Therefore I’d also direct you to Story By Robert McGee as well as Poetics by Aristotle. Both of these books look at story in a mechanical sense, and explain the precise methods storytellers (both ancient Greek ones and modern Hollywood ones) use to evoke emotions in the audience. These principles almost directly translate to game design.

After that I’d suggest looking at Chris Crawford’s list of books all game designers should read. Unfortunately I can’t find a copy of the list on the internet, but it’s at the end of his book Chris Crawford on Game Design

I forgot to include Homo Ludens by Johan Huizinga. It’s an older book, with more of an anthropological bent, but explains the psychology of play really well. It’s also where the concept of the “magic circle” – i.e. the semi-separated game space where we act according to a different set of rules than in real life – comes from.

Posted in Design | Leave a comment

Jordan

Ever since I was a little kid, I’ve been inspired by stories of american slaves escaping north through the Underground Railroad.

I built this game prototype to see how these stories could play out in an interactive experience.

The build of the game is in a decidedly Alpha state. The core experience is there, but it’s missing lot of models / animations / sounds. Especially the slave hunters – who are pink capsules – and the cabin at the end of the game – which is a pink cube.

I’d love to develop this game further sometime.

Jordan – Windows

Jordan – Mac

Posted in Design | Leave a comment

Monster

monster_feature

I’ve always been fascinated by simple pleasure found in physical play where the rules are enforced socially rather than mechanically. My kids have given me plenty of opportunities to experience this.

This game is an experiment to see if rules can be socially enforced by an NPC. I think it works pretty well.

Play Monster

Posted in Design | Leave a comment

One Button Mayhem

One Button Mayhem is Starcraft – simplified in to a one-button game.

I made this custom map a few years ago based on my earlier game Squirrel Fight. My goals was to convey a full RTS experience in a one-button game. In One Button Mayhem you tap the button to spawn a zergling and hold it down longer to spawn larger units.

The map should still be available on battle.net, but I haven’t checked in a while.

I got a lot of positive feedback from people in the Starcraft community – including a feature on SC2Mapster.com, a shout-out from Day[9], and a cute replay of Korean pro-gamer Sen playing it.

I learned a whole lot about game balance in making this game – in particular that a balanced game is by no means a fun game, and often quite the opposite. It takes a lot of work to keep optimal unit combinations from becoming overpowered and leading to long boring matches. And it’s amazing how much a tiny change – say +1 hit point here or +1 damage there – affects the final game.

People in the Starcraft community sometimes complain about game balance, but having seen the amount of work that goes into it, I’m amazed at how well the designers at Blizzard have done to make Starcraft both balanced and  fun.

Posted in Design | Leave a comment

Squirrel Fight

squirrelFight_feature

I made Squirrel Fight for a one-button game competition in 2009. The idea for it hit me as I was riding my bike home one day and by that evening I had my first prototype. It’s an RTS game – like Starcraft – but with extremely simple controls.

It’s a two-player game, so you’ll have to grab someone nearby and play with them.

 

Posted in Design | Leave a comment

Water Cooler

This one requires some explanation.

In 2009 I was a new graduate student in the Interactive Media program at USC (now the Interactive Media and Games program). One night during our weekly seminar, Scott Fisher – head of the program at the time – announced that because students kept stealing his water bottles he was going to put a new water cooler in the lab. The new water cooler came, and worked great for about 10 days – until we drank all the water in the two provided jugs.

Weeks went by with no replacement jugs. We worked late nights in the lab – groups of students huddled around glowing monitors furiously trying to make awesome games  - with that dry husk of a water cooler leering at us, mocking our thirst.

One night I’d finally had enough. Taking a cue from our many in-class discussions on “Serious Games” and “Games for Change” I opened up Adobe Flash, and in an hour or so built a game. A game with a powerful contemporary message. A game that would show the elites that they could no longer ignore our suffering. A game that could inspire all humankind to lay aside our petty differences and be united in the cause of ensuring well-hydrated game designers!

And that was how Water Cooler was made.

IMDWaterCooler

Anyway it worked. You can still see the reaction to it on the USC Interactive website ( look for Scott Fisher’s response :) ). New water arrived shortly afterwards and the cooler was finally filled.

I worked in that lab for 3 more years, and every time I drank from that water cooler I felt the satisfaction of having made the world a better place.

 

Posted in Design | Leave a comment