From bbbeaad9cda393e317ff9c43e181b7bdd3def6c3 Mon Sep 17 00:00:00 2001 From: kevinstadler Date: Thu, 7 Sep 2023 16:34:11 +0200 Subject: [PATCH 1/2] Add sound library reference post-processing steps to refBuild script --- README.md | 5 +- ReferenceGenerator/processingrefBuild.sh | 115 +++++++++++++++++++++++ 2 files changed, 118 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8406893..362f653 100644 --- a/README.md +++ b/README.md @@ -50,8 +50,9 @@ Now you are ready to run the doclet: 1. `cd` into the `processing-doclet/ReferenceGenerator` folder. 2. Run `ant compile`. -3. Run `./processingrefBuild.sh` if you are updating all the repositories or `./processingrefBuild.sh processing`, `./processingrefBuild.sh sound` or `./processingrefBuild.sh video` if you are updating a single repository. -4. After the new JSON files are created, move into `processing-website` and run `npx prettier --write content/references` to format the JSON files. +3. Run `./processingrefBuild.sh` if you are updating all the repositories or `./processingrefBuild.sh processing`, `./processingrefBuild.sh sound` or `./processingrefBuild.sh video` if you are updating a single repository. The script requires the following external dependencies to run successfully: + - all repositories: `npx` for pretty-fying the doclet JSON + - sound library only: `jq` and `sponge` for post-processing the documentation of subclasses. Install the dependencies by calling `apt-get/brew install jq moreutils` ### Update the website diff --git a/ReferenceGenerator/processingrefBuild.sh b/ReferenceGenerator/processingrefBuild.sh index 7573b39..e9c272f 100755 --- a/ReferenceGenerator/processingrefBuild.sh +++ b/ReferenceGenerator/processingrefBuild.sh @@ -58,6 +58,28 @@ if [ $# -eq 0 ] FOLDERS="$PROCESSING_SOUND_PATH/src/processing/sound/*.java" else echo "Option '$1' not valid. Should be 'processing', 'sound' or 'video'" + exit 1 +fi + +if [ $# -eq 0 -o "$1" = 'sound' ]; then + # check for jq and sponge + + HASDEPENDENCIES=0 + if !command -v jq &> /dev/null + then + HASDEPENDENCIES=1 + fi + if !command -v sponge &> /dev/null + then + HASDEPENDENCIES=1 + fi + if [ $HASDEPENDENCIES -eq 1 ]; then + echo "Could not find dependencies 'jq' and/or 'sponge' required to build Sound library reference, please run: brew/apt-get install jq moreutils" + exit 1 + fi + +# sound library reference needs a clean slate to handle subclass documentation correctly + rm $REFERENCES_OUT_PATH/sound/* fi echo "[REFERENCE GENERATOR] Generating new javadocs..." @@ -73,3 +95,96 @@ javadoc -doclet ProcessingWeblet \ -encoding UTF-8 \ $FOLDERS \ -noisy + + +# move into `processing-website` and run npx prettier +if command -v npx &> /dev/null +then + echo + echo 'Calling `npx prettier`' + echo + npx --yes prettier --write $REFERENCES_OUT_PATH || exit 1 # TODO remove translations/en from path? +fi + +# DO POST-PROCESSING FOR THE SOUND LIBRARY (move reference entries from superclasses down into subclasses) + +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 + # remove superclass method file + rm "$infile" + done + echo + # sort methods listing in class files alphabetically + for subclass in $subclasses; do + jq '.methods|=sort_by(.name)' $subclass.json | sponge $subclass.json + done +} + +if [ $# -eq 0 -o "$1" = 'sound' ]; then + echo + echo "Performing post-processing of Sound library reference" + echo + THISDIR=`pwd` + cd $REFERENCES_OUT_PATH/sound + superclass=SoundObject subclasses="AudioIn Noise Oscillator" CopyAndReplace # TODO AudioSample ?? + + 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 + + # superclass=AudioSample subclasses="SoundFile" CopyAndReplace + cd "$THISDIR" + echo "Sound library post-processing completed." +fi + + +if ! command -v npx &> /dev/null +then + echo 'WARNING: npx is not installed, so could not run `npx prettier --write content/references`' + echo '`git diff` might show lots of modified files that only differ in JSON formatting, not content.' + exit 1 +fi From 2a825a7fbdfd4f4cca2d051926606d488255f657 Mon Sep 17 00:00:00 2001 From: kevinstadler Date: Tue, 3 Oct 2023 12:58:28 +0200 Subject: [PATCH 2/2] Update sound library reference post-processing --- ReferenceGenerator/processingrefBuild.sh | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/ReferenceGenerator/processingrefBuild.sh b/ReferenceGenerator/processingrefBuild.sh index e9c272f..b97c8bc 100755 --- a/ReferenceGenerator/processingrefBuild.sh +++ b/ReferenceGenerator/processingrefBuild.sh @@ -78,8 +78,9 @@ if [ $# -eq 0 -o "$1" = 'sound' ]; then exit 1 fi -# sound library reference needs a clean slate to handle subclass documentation correctly - rm $REFERENCES_OUT_PATH/sound/* + # sound library reference needs a clean slate to generate subclass + # documentation correctly + rm -f $REFERENCES_OUT_PATH/sound/* fi echo "[REFERENCE GENERATOR] Generating new javadocs..." @@ -171,12 +172,14 @@ if [ $# -eq 0 -o "$1" = 'sound' ]; then cd $REFERENCES_OUT_PATH/sound superclass=SoundObject subclasses="AudioIn Noise Oscillator" CopyAndReplace # TODO AudioSample ?? + # superclass=AudioSample subclasses="SoundFile" 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 - # superclass=AudioSample subclasses="SoundFile" CopyAndReplace + superclass=Effect subclasses="AllPass Delay Filter Reverb" CopyAndReplace + superclass=Filter subclasses="BandPass HighPass LowPass" CopyAndReplace + + superclass=Analyzer subclasses="Amplitude BeatDetector FFT PitchDetector Waveform" CopyAndReplace cd "$THISDIR" echo "Sound library post-processing completed." fi