[PyCon] Survival kit - docs review

Question

[PyCon] Survival kit - docs review

eviau-sat opened this issue 2 years ago · 0 comments

[PyConFr2023] Survival kit - docs review

Notes générales

Le Survival kit est un bon début - voici mes commentaires tel que discuté.

Je pense qu'on pourrait ajouter des en-têtes (headings) pour faciliter la navigation et découper les exemples présentés.

Séparer chaque exemple en utilisant du texte au lieu d'un seul code block - et activer le bouton copier/coller dans la documentation ?

Notes complètes

# This is a condensed Sardine tutorial. Copy and paste this file in a working buffer.

Je pense qu'on pourrait expliquer ce qu'on veut dire par working buffer en donnant un exemple.

# You can evaluate pretty much every example and follow along. By the end of this file,

Peut-être donner une indication sur comment évaluer - ou ajouter un lien vers les instructions pour les éditeurs de texte ?

# you should have a better understanding of Sardine.

En général, ça aide d'être spécifique sur quels apprentissages sont espérés de l'exercice.

# Make sure that you have the same configuration as me.
# I have toggled pretty much everything in sardine-conf.
# BPM: 120.0,BEATS: 4 SC: [X], DEFER: [X] MIDI: Sardine

Est-ce que la ligne # BPM: 120.0,BEATS: 4 SC: [X], DEFER: [X] MIDI: Sardine est suffisante pour décrire la configuration ?

Peut-être ajouter un lien sur les instructions de configuration ?

Suggestion: placer un premier en-tête ici pour mentionner qu'on commence le premier exemple.

# You can now evaluate every code example I'm providing. 
# Let's start with a basic hello world!

@swim
def hello_world():
    print('Hello World!')
    again(hello_world)

Suggestion: mentionner le résultat attendu de l'exécution du code avant de donner le code.

Par exemple: Let's print 'Hello World!' in the terminal - multiple times. Evaluate the following code in a working buffer:

silence() # Silence will stop everything.
panic() # Panic will kill everything (useful when you lost control).

J'ajouterais ces deux instructions au tout début - avant de jouer quoique ce soit puisque c'est un incontournable.

# Let's break it down. This is just a normal Python function.

Ici, "normal" est pas nécessairement bien défini...

Suggestion: Let's build this first example from the beginning. First, we define a function:

def hello_world():
    print('Hello World!')

# However, we are adding the swimming decorator. It allows the
# function to loop automatically and will allow you to reevaluate
# it whenever you want.

Suggestion: To allow the function to loop, we add a @swim decorator. We can now re-evaluate the function whenever we want. Our example is now:

@swim
def hello_world():
    print('Hello World!')

Continuons !

# This is not enough, because we need to explicitely tell our 
# function to come back around :)

Suggestion: Enable looping by adding the again() instruction to the function definition.

@swim
def hello_world():
    print('Hello World!')
    again(hello_world)

# We call this pattern a 'temporally recursive function' or a 
# 'swimming function' because fishes are funnier.

Suggestion: This is what we call a temporally recursive function, or poetically speaking, a swimming function - fishes are funnier.

Je placerais le second en-tête ici. Suggestion: ## Making sounds with Sardine

Now we are going to replace printing by sounds. Call SuperDirt with D() and let's play some bass and drum by using bd as an argument. This will give us a kick.

@swim
def hello_world():
    D('bd')
    again(hello_world)

# We now have a kick. Let's change the recursion speed.

Est-ce vraiment de la récursion ou plutôt une boucle ?

@swim
def hello_world(p=0.5):
    D('bd')
    again(hello_world, p=0.5)

# This is twice as fast. Let's add more complex rhythms.

Suggestion: ajouter une en-tête. Titre possible: Creating rhythms with iterators

@swim
def hello_world(p=0.5, i=0):
    rhythm = Pat('0.5, 0.25, 1', i)
    D('bd')
    again(hello_world, p=rhythm, i=i+1)

# There is quite a lot of complexity already! Let's break it
# down by falling back to something simpler.

Suggestion: enlever cet exemple puisqu'on n'y revient pas directement par la suite ?

@swim
def hello_world(p=0.5, i=0):
    D('bd, drum:8, cp, drum:8', i=i)
    again(hello_world, p=0.5, i=i+1)

# This is a four on the floor. Note that we are using iterators
# quite a lot. They are super important in Sardine. In the last
# example, we are moving forward in the pattern by incrementing
# the i variable everytime we loop around.

Question: peut-être ajouter un lien vers Wikipedia ou autre pour la définition de four on the floor

Suggestion: Ajouter une section qui présente les itérateurs avec un exemple minimal:

As a musician, a live coder or a sound artist, you might want to play more than one sound.

Running the following code will play them at about the same time:

@swim
def hello_world(p=0.5):
D('bd')
D('foo')
again(hello_world, p=0.5)

To play two sounds sequentially, we can use iterators:

@swim
def hello_world(p=0.5,i=0):
    D('bd, foo', i=i)
    again(hello_world, p=0.5, i=i+1)

@swim
def hello_world(p=0.5, i=0):
    D('bd, drum:8, cp, drum:8', i=i)
    D('jvbass:[0:10]', i=i)
    again(hello_world, p=0.5, i=i+1)

# Super cool! Let's try to add a random number to the i=i argument.

Suggestion: ne pas utiliser d'autres librairies que Sardine dans le Survival kit question de se concentrer sur Sardine.

from random import randint

@swim
def hello_world(p=0.5, i=0):
    D('bd, drum:8, cp, drum:8', i=randint(1,10))
    D('jvbass:[0:10]', i=randint(1,1000))
    again(hello_world, p=0.5, i=i+1)

# We are now randomly peeking in the pattern. Let's now play the 
# pattern in reverse.

Le bloc précédent est à effacer car on enlèverait tout ce qui fait appel à la bibliothèque random - ou on peut l'ajouter en bonus à la fin.

@swim
def hello_world(p=0.5, i=0):
    D('bd, drum:8, cp, drum:8', i=-i)
    D('jvbass:[0:10]', i=-i)
    again(hello_world, p=0.5, i=i+1)

# Negative iteration, we are going in the other direction!
# What if we play directly with i=i+1?

Suggestion de rédaction:

Iterators can take a diverse range of values to obtain a variety of effects. Let's explore the current possibilities.

Changing the incremental value in the `again()` function will allow us to skip some elements in the pattern:

@swim
def hello_world(p=0.5, i=0):
    D('bd, drum:8, cp, drum:8', i=i)
    D('jvbass:[0:10]', i=i)
    again(hello_world, p=0.5, i=i+2)

Ajouter une en-tête. Suggestion: Adding rhythm to iterators by using the Pat object

# Now we are skipping some pattern elements! This is yet another easy
# variation on our last pattern. 

@swim
def hello_world(p=0.5, i=0):
    rhythm = Pat('1/3, 2/3', i)
    D('bd, drum:8, cp, drum:8', i=i)
    D('jvbass:[0:10]', i=i)
    again(hello_world, p=rhythm, i=i+2)

# I am using the Pat(pattern, iterator) object to add some rhythm to
# my recursions. Yet another layer of complexity, but you know what?

Suggestion: décrire ce qu'on peut entendre pour confirmer les apprentissages.


silence()

Ajouter un en-tête qui mentionne qu'on passe à la prochaine section.

Suggestion: Writing Sardine in short form

In the last section we ended with the following code:

@swim
def hello_world(p=0.5, i=0):
rhythm = Pat('1/3, 2/3', i)
D('bd, drum:8, cp, drum:8', i=i)
D('jvbass:[0:10]', i=i)
again(hello_world, p=rhythm, i=i+2)

We can rewrite the same code in a short form called a surfboard that you can use to surf around the system:

Pa >> d('bd, drum:8, cp, drum:8', p='1/3,2/3')
Pb >> d('jvbass:[0:10]', p='1/3,2/3')

# You can also write things like this. We call these 'surfboards'
# because they feel great for surfing around in the system.

Le commentaire précédent serait mieux avant le code.

Pa >> None
Pb >> None

# To stop these, you can just assign None to them using the >> special
# operator. You can also make them faster or slower by using span=

Stop the surfboards by assigning None to them:

Pa >> None
Pb >> None

We are using the special >> operator - link to more docs about this.

Make the surfboard slow down or speed up by setting the span argument:

Pa >> d('bd, drum:8, cp, drum:8', p='1/3,2/3', span=0.5)
Pb >> d('jvbass:[0:10]', p='1/3,2/3', span=0.5)

Pa >> d('bd, drum:8, cp, drum:8', p='1/3,2/3', span=2)
Pb >> d('jvbass:[0:10]', p='1/3,2/3', span=2)

# It can get weird very easily, especially when you start playing with
# the period argument (p). I'll let you try and see for yourself!

Si c'est une découverte, peut-être ajouter une mention optionnel ?

Pa, Pb, Pc, Pd, Pe, Pf, Pg, Ph, ...
PA, PB, PC, PD, PE, PF, PG, PH, ...

# There is 48 'Players' to get you running with surfboards. Note that
# we were previously using D, but we use d for surfboards.

Je ne sais pas trop si c'est clair qu'ici, on démontre qu'il y a d'autres Players possibles - ou autre ?

silence()

Idée: mettre des silence() après chaque exemple de code pour que ce soit plus simple de copier/coller/exécuter.

Fin des notes

Je m'arrête ici pour le moment, hésite pas si tu veux d'autres commentaires plus tard !