Python Faded Parsons Problems with Visual Output

This tool should allow you to run Faded Parsons Problems in static page in the browser, with visual results, using pyp5js (pyodide and the p5js canvas) to show the sketch results, as written with puzzle blocks in a dialect close to py5 in imported mode style.

Based on faded-parsons-static by Pamela Fox, with help from many people! With special thanks to Luciano Ratamero who adapted & inserted pyp5js and made this all work.

Work in progress, working prototype!

Check out the tool in action at https://abav.lugaralgum.com/python-parsons-visual/

A quick way to make and publish your own puzzles

You can fork this repository, edit the YAML files in the parsons_prob folder as explained bellow, and set the GitHub Pages settings to publish your own page, or upload on some other webhosting server. This tool is based on "static pages", so uploading the files (mostly html, js, yaml, images and etc.) is all there is to it.

If you want to know more and contribute with this tool/project

Setting up a local development environmet

Be sure to have nodejs installed. To install nodejs, go to their download page and download the installer for your operating system: https://nodejs.org/en/download/

We will assume you have at least some familiarity with the command line. After installing, open a terminal, go to the project's folder using cd (the one you're in right now) and run:

npm install

This will install all the dependencies for the website.

If you don't have npm installed, double check the installation instructions for nodejs for your operating system.

Running the website locally

From the download directory:

npm run dev

This will start a local server at http://localhost:8000/ where you can see the website. Also, whenever you change something in the code, reload the page to see the changes.

Building the website

To make the site ready for deployment, run:

npm run build

This will recreate the dist folder with the website ready to be deployed.

Deploying the website

The website can be deployed anywhere since it's entirely static. The working prototype example at https://abav.lugaralgum.com/python-parsons-visual/ is served using the files index.html (home page), problem.html (puzzle page) and the folder with the puzzles YAML data and assets. You can use the Codeberg Pages or GitHub Pages feature on your own fork of the repo to host it. Note the README.md should not become the starting page due to the index.html presence.

Adding a new problem

Add files to the parson_probs folder:

• problem_file.yaml: This is a YAML file that includes the problem description (HTML) and code lines with blanks.

• You should add an image to the description, like problem_file.png, in the same folder.

• Example 000_variables.yaml that uses 000_variables.png in the same folder:

problem_name: Variables

problem_subtitle: assignement

problem_category: Getting Started

problem_description: |
  <img src="parsons_probs/000_variables.png"></br>
  <h5>Variables</h5>
  <code>assignement</code></br>
  Organize blocks of lines to make the drawing above.
  Notice indentation matters.

code_lines: |
  def setup(): #0given
  size(400, 400) #1given
  background(200) # fundo cinza
  nome = '!BLANK'
  text(nome, 20, 180)  # desenha o texto de `nome`
  # Se tentar usar a variável `a` antes de criar...
  # ... vai ter um erro do tipo NameError (não conheço `a`)
  a = 10  # cria a variável `a` que aponta para o valor 10
  square(a, 10, 140)  # desenha um quadrado de lado 140 em x:10, y:10
  a = a + 145  # calcula o valor de `a + 145` e muda a variável `a`
  square(a, 10, !BLANK)  # desenha um quadrado de lado 140

Then you can access the new problem at .../problem.html?name=problem_file

Updating the index/home page

The Python script update_index.py, that depends on Beautiful Soup 4, will look for YAML problems in the parsons_probs folder, check the category and update the index.html with links to all the problems found.

Automating YAML generation from puzzle source code

Also inside the parson_probs folder, you will find some .py files that contain py5 code, in imported mode style for a problem, with added annotations like #0given as explained above, and some extra special comments containing !REMOVE on some lines, as well as commented out lines with code containing !BLANK. Those scripts will generate the YAML problem file and the image file for the problem description.