4.4.4. Software development environment

Unless you have a strong preference for another IDE that you are sufficiently expert with to configure yourself, it is recommended that we all use the same IDE. Currently, PyCharm is recommended for CTGames development because of its ability to configure file watchers and support for Conda environments.

4.4.4.2. Install PyCharm

  1. Install PyCharm

    Install PyCharm by opening a terminal in any directory (Ctrl-Alt-t) and entering

    sudo snap install pycharm-community --channel=2023.2/stable --classic

    Start PyCharm by entering

    pycharm-community &

    If you are starting PyCharm for the very first time, you may have some of the following things to do:

    • at the “PyCharm User Agreement” popup window, check the I confirm… checkbox and click Continue

    • at the “Data Sharing” popup window click Send Anonymous Statistics (it’s polite to do this since we’re using the free community version of their IDE)

    • if you are asked about settings and plugins, just click the button to accept all defaults

    Eventually you will see the “Welcome to PyCharm” popup window. Keep this window open because there are a number of steps to perform as detailed in the next subsections.

    Note

    If you have used PyCharm before and have some open files, just click File ‣ Close Project for each open project to get back to the “Welcome to PyCharm” popup window.

    Note

    Depending on your graphical environment, you may be able to create a shortcut for PyCharm on your Launcher/Desktop [for example, in Ubuntu you can find its icon on the Launcher on the left-hand-side, right-click on the icon, and select Add to Favourites].

  2. Import settings

    • From the “Welcome to PyCharm” popup window click Customize ‣ Import Settings…

    • Select the file /home/username/gitlab.cs.nuim.ie/ctgames/ctgames/PyCharmCE2020.2_settings_archived.zip (where username is your own username)

    • In the box that pops up labeled “Select Components to Import”, click Select All and then OK

    • Click Import and Restart when prompted

  3. Install plugins

    • From the “Welcome to PyCharm” popup window, click Plugins and install the “File Watchers” plugin

4.4.4.3. Configure PyCharm

  1. Open the CTGames project

    • From the “Welcome to PyCharm” popup window, click Projects ‣ Open and in the directory listing click the directory /home/username/gitlab.cs.nuim.ie/ctgames/ctgames where username is your own username

    • Click OK

    • At the “Trust and Open Project ‘ctgames’?” popup window, check the box Trust projects in… and click Trust Project

    • Wait; grab a cup of coffee as it can take more than 5 minutes for PyCharm to parse the CTGames project (note the progress bar at the bottom of the PyCharm app showing background tasks indexing the project)

    Note

    You might get popup windows from PyCharm about a “Suggested plugin” or to reconfigure or upgrade the Python interpreter. You are welcome to experiment (it is straightforward if a little time consuming to undo these changes). However, if you wish the exact same development environment as most other students in the team (to make it easier to find help with problems), just X each of these popup messages.

  2. Associate the project with the ctgames Conda environment

    • From within PyCharm open the main menu by clicking on the hamburger icon near the top-left of the screen or press Alt-\

    • Select File ‣ Settings… to open the “Settings” window

    • Click Project: ctgames ‣ Python Interpreter

    • In the dropdown box labelled “Project Interpreter”, select the option Python 3.8 (ctgames)

      Note

      Only if there is no such option in the dropdown box, carry out the following steps.

      1. Click the gear icon on the extreme right-hand side and select Add… to open the “Add Python Interpreter” dialog box

      2. In the left-hand pane of the “Add Python Interpreter” dialog box, select Conda Environment

      3. In the right-hand pane select the Existing environment radio button

      4. For the text box labelled “Interpreter”, click the … button, select the file /home/username/miniconda3/envs/ctgames/bin/python, where username is your own username (double click on this file, or click OK to return to the “Add Python Interpreter” dialog box)

      5. The text box labelled “Conda executable” should be automatically populated. If not, set it to /home/username/miniconda3/bin/conda, where username is your own username

      6. Check the check box Make available to all projects

      7. Click OK in the “Add Python Interpreter” dialog box to return to the “Settings” window

    • In the “Settings” window, click Apply to complete the task, if it is clickable. Don’t click OK just yet.

  3. Integrate tools with PyCharm

    Note

    The instructions that follow will not work unless PyCharm has completed its background tasks of indexing the project (mentioned a few lines above, a visible progress bar at the bottom of the PyCharm app will indicate of indexing is still ongoing).

    Keeping the “Settings” window open (if you’ve already closed this window, no problem, just make sure the CTGames project is open and click File ‣ Settings…)

    • Select Tools ‣ File Watchers

    • You should see a file watcher called “blackpp”. If it is not enabled, click the checkbox to enable it.

      Note

      Only if there is no such file watcher “blackpp” in the list, carry out the following steps.

      1. On the extreme right-hand side click the button that has an arrow like ↙ (the button with the tooltip “Import”)

      2. In the “Choose a File with Watchers” dialog box, double click on the file /home/username/gitlab.cs.nuim.ie/ctgames/ctgames/pycharm_watchers.xml (where username is your own username), or alternatively click it once and click OK

      3. Click OK in the “Settings” window to close it

    Note

    Once in a while when PyCharm is open it will pop up a message asking you to update the File Watchers plugin. If you update, it may delete your current file watchers. If this happens, just follow the steps in the note above.

  4. Games you create will appear in CTGames/ctgames in the project directory structure visible in PyCharm.

    Firefox is the recommended browser to run CTGames web app games, but if you encounter any strange behaviour, Chromium and Chrome are also there to check if the strange behaviour is due to CTGames or one particular browser.

    Bookmark the chapter “Game development” to read later how to run other students’ games and how to create your own.

4.4.4.4. Install a RST editor for documentation

Note

This is not required unless it has been agreed that you will contribute to the CTGames documentation.

The documentation for CTGames is written using a markup called reStructuredText (RST). The RST editors I have tried are

PyCharm

PyCharm has built-in RST support with a live preview (useful when new to RST), and spell checking, however (as of 2020) it has trouble with the kind of link used in the CTGames documentation where sections titles can have style formatting (e.g. when they contain function names). It would be nice if it worked because then we could use the same editor for code and documentation.

Formiko

Formiko has spell checking, live preview, but (as of 2020) like PyCharm, does not handle links with formatting. It automatically synchronises scrolling in the preview pane. It is quite stable. It seems to be in maintenance mode rather than active development.

ReText

ReText has spell checking and live preview. Unlike Formiko, it does not automatically synchronise scrolling in the preview pane, however it does stay where you put it and so is workable. In version 7.1.0, it has an annoying habit of occasionally not letting me save my document – I have to close the edited document to effect a file save. It doesn’t understand common text style formatting roles such as :seealso:, :file:, :guilabel:, and so on. However, it renders documents more closely to the way Sphinx (the processor used by Read the Docs) does than the others. It is under active development.

I propose to use ReText. To install it, open a terminal in any directory and enter

sudo apt update
sudo apt upgrade
sudo apt install retext
Basic configuration steps include

  • Click Edit ‣ Spell check ‣ Enable

  • Click Edit ‣ Spell check ‣ Set locale and enter “en_IE” (without quotes)

The ReText editor can be run by finding the appropriate icon, or by associating all RST files (files with filenames ending with .rst) with this program.