Update sound library reference categories/subcategories

[kevinstadler]

Instead of listing all sound library classes as a flat list of 'main' categories, there is now a category-subcategory structure with more informative category names, i.e.:

• Effects
  • BandPass
  • Delay
  • ...
• Oscillators
  • Pulse
  • SawOsc
  • ...

[SableRaf]

Hey @kevinstadler ,

Looks good to me! I saw the corresponding changes you made to the processing-sound repo in commit dfe6fb2. It's a neat shift to the category-subcategory structure, making the reference more structured and readable. I'll merge your changes and deploy them with the next release of the website.

I also noticed the issues you raised on the processing-doclet repo: https://github.com/processing/processing-doclet/issues/4 and https://github.com/processing/processing-doclet/issues/3. For future reference, did you use a modified version of the doclet script to produce the changes in this current PR??

Appreciate your efforts on this!

Best, Raphaël

[kevinstadler]

The doclet script was the same, I just ran some extra post-processing on the json files that were created by ./processingrefBuild.sh sound

For reference here is the version of the script that produced the final json files of this pull request. I started off using only unix staples like sed, but for the json editing I had to make use of jq and sponge (tiny dependencies but still dependencies). The doclet instructions already recommend to run npx prettier after doclet generation, so I suppose there is some space for automating post-processing steps that require dependencies, maybe directly in processingrefBuild.sh?

#!/bin/sh

cd "`dirname $0`/content/references/translations/en/sound/"

npx prettier --write .

function CopyAndReplace ()
{
    # remove class file which was only needed to trigger generation of the per-method .json files
    if [ ! -f "$superclass.json" ]; then
        echo "Couldn't find superclass files, are you running this script a second time since generating the doclets?"
        exit 1
    fi
    rm "$superclass.json"

    echo "$superclass"
    for infile in $superclass*; do
        # for every _method_.json: create a copy for every subclass
        echo " - $infile"
        for subclass in $subclasses; do
            outfile=`echo $infile | sed "s/$superclass/$subclass/"`
            if [ -f $outfile ]; then
                echo "   . $outfile already exists, subclass must have its own @webref documentation"
            else
                echo "   > $outfile"

                # append method descriptions to subclass
                jq --slurpfile method $infile --arg anchor "`basename $outfile .json`" '.methods += [{ "anchor": $anchor, "name": $method[0].name, "desc": $method[0].description}]' $subclass.json | sponge $subclass.json

                # change @webref (sub)categories
              if [ "$superclass" = "SoundObject" ]; then
                    # fix discrepancy between class name and webref category name
                    prettyclass=$subclass
                    if [ "$subclass" = "Oscillator" ]; then
                        prettyclass="Oscillators" # fix category name
                  elif [ "$subclass" = "AudioIn" ]; then
                    prettyclass="I/O"
                  fi

                    sed -e "s,\"category\": \"SoundObject\",\"category\": \"$prettyclass\"," \
                            -e "s/\"subcategory\": \"\"/\"subcategory\": \"$subclass\"/" \
                            -e "s/\"classanchor\": \"$superclass\"/\"classanchor\": \"$subclass\"/" \
                                $infile > $outfile
              else
                    # all concrete classes simply replace the subcategory
                    sed -e "s/\"subcategory\": \"$superclass\"/\"subcategory\": \"$subclass\"/" \
                            -e "s/\"classanchor\": \"$superclass\"/\"classanchor\": \"$subclass\"/" \
                                $infile > $outfile
              fi
            fi
        done
      rm "$infile"
    done
    echo
    for subclass in $subclasses; do
        jq '.methods|=sort_by(.name)' $subclass.json | sponge $subclass.json
    done
}

superclass=SoundObject subclasses="AudioIn Noise Oscillator" CopyAndReplace

superclass=Oscillator subclasses="Pulse SawOsc SinOsc SqrOsc TriOsc" CopyAndReplace
superclass=Noise subclasses="BrownNoise PinkNoise WhiteNoise" CopyAndReplace
superclass=Effect subclasses="AllPass BandPass Delay HighPass LowPass Reverb" CopyAndReplace
superclass=Analyzer subclasses="Amplitude BeatDetector FFT Waveform" CopyAndReplace

cd `dirname "$0"`