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: processing/processing-doclet#4 and processing/processing-doclet#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"`