search

DrMarc / slab

python classes for working with sounds and conducting psychoacoustic experiments
MIT License
22 stars 7 forks source link

Nitpicking on examples in the README #25

Closed hadware closed 3 years ago

hadware commented 3 years ago

Your examples are great, but some things did bug me:

  1. The first example has a tab before each of its line, which forced me to "detab" it before being able to run it (i know, i'm lazy, but so is everyone).
  2. Examples that show some typical outputs are a bit confusing, you should switch to a fake python prompt or fake ipython prompt style of code examples to represent this, such as 
    >>> sig = slab.Sound.pinknoise(nchannels=2) # make a pink noise
>>> sig.duration
1.0

    (The current out : 1.0 format kind of feels like a type annotation).

Btw, the example mentioned above has a typo in the n_channels argument :wink:

OleBialas commented 3 years ago

I agree that this layout is more intuitive. However if we change it in the readme we should change everything (docstrings, readthedocs) to the same format, @DrMarc what do you think?

hadware commented 3 years ago

My advice is that you should only change examples where some output is shown, otherwise it's just fine as it is

DrMarc commented 3 years ago

Consistency and convenience are king. We should decide on one format and stick to that throughout the examples. This format should be easy to copy over to an iPython console. The fake iPython style is very common and may be the best option. @OleBialas - could you check whether it interferes with sphinx? We also need to go over all examples and propagate the recent naming changes (nsamples -> n_samples, nchannels arguments, etc.).

hadware commented 3 years ago

This format should be easy to copy over to an iPython console.

I agree, the >>> some.code() format is pretty but thoroughly annoying when it comes to copying things over to your code/the console.

DrMarc commented 3 years ago

Ok. Having your input really helps here; we work mostly with an editor and an ipython console side-by-side, and ipython happily ignores the leading >>>. If that's a problem in other environments, then we can go with unindented code and put the output examples in comments. That would be clear and copy nicely.

hadware commented 3 years ago

Having your input really helps here;

Alright, here's a breakdown of what works for me with the >>> my.code() syntax and what doesn't:

Hope that helps.