Adds Virtual Tennis Tutorial

docs/conf.py

@@ -43,6 +43,7 @@
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
+    'sphinx_tabs.tabs',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/tutorials/index.rst

@@ -5,3 +5,7 @@ Tutorials live here, except for the basic Quick Start tutorial.
 
 A tutorial is an complete project that takes you from an empty file to a
 working game.
+
+
+.. toctree::
+   virtual-tennis/index

docs/tutorials/virtual-tennis/index.rst

@@ -0,0 +1,78 @@
+===============================
+Virtual Tennis
+===============================
+
+.. toctree::
+   :hidden:
+   :maxdepth: 0
+   :titlesonly:
+
+   setup
+   window
+
+In this tutorial, we're going to build a game virtual tennis game in the vein
+of Pong_. We're going to go through the whole process: planning our approach,
+breaking out individual tasks, setting up our environment, and coding.
+
+Before you start writing code on a project, it's best to think about the game
+we're trying to make. For research, go try this implementation of
+`Pong <https://archive.org/details/PONGV2.11996DJTAction>`_ on the internet
+archive.
+
+Let's think about what's going on in this version:
+
+#. It opens on a menu with sample play happening in the background.
+#. The menu explains all the controls.
+#. When you start a one player game, you receive control of one of the paddles.
+#. The ball launches, and you need to move up and down to deflect the ball.
+#. The ball bounces off the top and bottom walls.
+#. If either of you miss the ball, the other player's score goes up.
+#. If a player reaches 15 points, the game ends with fanfare and the word
+   "Winner!" printed repeatedly on that side of the screen.
+#. Then it goes back to the menu.
+
+Now that we've looked at an example of our project, let's identify the
+important parts:
+
+* The core game play is a ball and two paddles, each controllable by a player.
+* The ball needs to be able to bounce off the top and bottom wall and either
+  paddle.
+* The paddles need to be able to move.
+* We need to be able to track the score.
+* We need to be able to end the game.
+
+This tutorial will break each of these requirements into smaller pieces so we
+can test features as we go.
+
+Before we get started, you'll need a few things done first:
+
+#. Install python 3.8 on your system. We suggest installing from python.org for
+   best results. For more information, see the
+   `Django Girls tutorial <https://tutorial.djangogirls.org/en/installation/#python>`_.
+   for more specific instructions on installation.
+#. Install a code editor. We suggest PyCharm, Sublime Text, GEdit or VSCode.
+   Extra information and suggestions can be found at
+   `Django Girls <https://tutorial.djangogirls.org/en/installation/#code-editor>`_.
+#. You'll also need to know the basics of Python. Again, Django Girls has a
+   great `tutorial <https://tutorial.djangogirls.org/en/python_introduction/>`_
+   for this.
+
+Once you have those things done, you can move on to our first step: setting up
+our project.
+
+
+( The following will be deleted before final publication.)
+
+1. A window
+2. A ball that bounces on the edges of the screen.
+3. A player paddle that can be moved.
+4. Collision between player paddle and ball.
+5. A score board tracking how many times the player hits the far side of the
+   screen.
+6. Removing the ball from play when it hits the far wall.
+7. Launching the ball with a key press.
+8. Removing the ball if it hits the player's wall.
+9. Adding a second player paddle.
+10. Adding a new score board for second player.
+11. End the game.
+12. Ideas for making the game your own.

docs/tutorials/virtual-tennis/setup.rst

@@ -0,0 +1,96 @@
+===============================
+Setup
+===============================
+
+For this project, we're going to want to have a project folder and a virtual
+environment set up. Follow along and we'll get that set up.
+
+.. note:: Before continuing, if you're new to software development, you
+   should pick a directory or folder on your computer to save your project. A
+   common name for this directory is ``src``. It can live anywhere you like. You
+   should copy the path from your file explorer and hold on to it, we're going
+   to use it later.  We reference this path as ``/path/to/src/``.
+
+So the first thing you need to do is open your terminal.
+
+.. tabs::
+
+   .. group-tab:: Windows
+
+      On Windows, there are two terminals: cmd and powershell. If you're not
+      sure which to pick, choose cmd. Future directions are written with this
+      terminal in mind.
+
+   .. group-tab:: MacOS
+
+      The MacOS default terminal is just called Terminal.
+
+   .. group-tab:: Ubuntu
+
+      (fill out later)
+
+With your terminal open, you're going to want to navigate to the
+``/path/to/src/``. After that, we'll set up a project directory, and then
+navigate into it. In the commands below, replace ``/path/to/src/`` with your
+specific path you saved earlier. The name ``virtual-tennis`` is a nice
+descriptive name for your project folder, but you can change the name if you'd
+like.
+
+.. warning:: Each of these steps has multiple commands. Make sure to enter them
+   one at a time and hit the enter or return key and wait until they stop
+   putting new text on the screen before the next command.
+
+On all systems:
+
+.. code-block::
+
+   cd /path/to/src/
+   mkdir virtual-tennis
+   cd virtual-tennis
+
+Our next step is to set up a virtual environment. We're going to use the python
+library ``venv`` for this. After creating it, we need to activate it, and
+install ``ppb``. Below, we call our virtual environment ``.venv``, but this is
+only one of many possible names. If you change the name, replace it in following
+commands with your new name. The structure in a virtual environment doesn't
+change based on its name.
+
+.. note:: A virtual environment is a way to isolate the requirements of your
+   project from other Python projects on your computer. This lets you have
+   projects with conflicting requirements, like two different versions of
+   ``ppb``.
+
+.. tabs::
+
+   .. group-tab:: Windows
+
+      .. code-block::
+
+         py -3.8 -m venv .venv
+         .venv\Scripts\activate
+         python -m pip install ppb
+
+   .. group-tab:: MacOS
+
+      .. code-block::
+
+         python3.8 -m venv .venv
+         source .venv/bin/activate
+         python -m pip install ppb
+
+   .. group-tab:: Ubuntu
+
+      (add later)
+
+The last step will depend on the code editor you've picked. If you're using an
+IDE (PyCharm, VSCode, or similar) you'll want to open your project in your IDE.
+
+If you're using a plain text editor (GEdit, Notepad++) open it, but don't create
+any files yet.
+
+Keep your terminal open, you're going to use it later. If you close it, you
+should navigate back to your project folder and activate the virtual environment
+again.
+
+With all of this out of the way, we can move on to our first step: Creating a
+window.

docs/tutorials/virtual-tennis/window.rst

@@ -0,0 +1,86 @@
+===============================
+Opening a Window
+===============================
+
+So we've installed everything we need, but it's always a good idea to make
+sure our environment is right before moving on. A good first step for any video
+game is to make sure you can make an empty window.
+
+Inside your `project directory`_ we need to create a file. Do so using your
+code editor, and call it ``main.py``. Make sure to open it so we can add code
+to it.
+
+.. note:: We're using ``main.py`` here, but like the name of your virtual
+   environment, this is just convention. If you change it, make sure to replace
+   the name ``main.py`` in any console commands shown later. We do suggest
+   keeping the name, though.
+
+If you haven't already, open up ``main.py`` in your code editor. Inside, add
+the following code:
+
+.. code-block:: python
+   :caption: main.py
+   :linenos:
+
+   import ppb
+
+   ppb.run()
+
+Save this file and go back to your terminal. There, you should enter the
+following command to run your game.
+
+.. code-block::
+   :caption: Terminal
+
+   > python main.py
+
+You should have a window open that looks like this:
+
+(Add image.)
+
+To run any python script (not just our ``main.py``) you call ``python``, add a
+space and then the name of the script you're wanting to run. There's lots of
+other options, but this is all you need to know so far.
+
+Before we continue, we're going to do one more thing. The default resolution of
+800x600 is great, but you might want a bigger (or smaller) window. We're going
+to add a constant value and give that to ppb to tell it how big of a window we
+want.
+
+.. code-block::
+   :caption: main.py
+   :linenos:
+   :emphasize-lines: 3,5
+
+   import ppb
+
+   RESOLUTION = (1200, 900)
+
+   ppb.run(resolution=RESOLUTION)
+
+Save this and rerun it and the screen should be bigger this time.
+
+The reason ``RESOLUTION`` is spelled with all caps is because this is a what
+programmers call a constant. As a community, Python developers use `special
+capitalization rules`_ to tell the difference between different kinds of
+variables. The value is what we call a tuple, which is collection of values
+that can't be changed. These values are the width and height of the window in
+screen pixels.
+
+Just defining this value isn't enough. The :class:`ppb.GameEngine` doesn't look
+for values, you have to tell it what you want. In this case the keyword argument
+`resolution` is how you inform ``ppb`` what you want. So in this case,
+``resolution=RESOLUTION`` is giving our constant to the engine to change the
+size of the window.
+
+You can change either the width or the height in ``RESOLUTION`` to find a
+window size you like. The Atari 2600 had a maximum resolution of 160x192, but
+this is exceptionally small on modern screens. It's better to pick bigger, we
+can manipulate the size of the things on the screen later. When you change the
+value, you should use ``python main.py`` again to see the result. Keep experimenting
+
+Once you've found a screen size and shape you like, we can move on to putting
+something on screen.
+
+.. _project directory: ../setup
+.. _special capitalization rules: https://www.python.org/dev/peps/pep-0008/

requirements-docs.txt

@@ -1,2 +1,3 @@
 sphinx
 sphinx_rtd_theme
+sphinx-tabs