Merge pull request #283 from edibotopic/metrics

update allmetrics

Makefile

@@ -23,6 +23,7 @@ help:
         "* check accessibility:                       make pa11y \n" \
         "* check style guide compliance:              make vale \n" \
         "* check style guide compliance on target:    make vale TARGET=* \n" \
+        "* check metrics for documentation:           make allmetrics \n" \
         "* other possible targets:                    make <TAB twice> \n" \
         "------------------------------------------------------------- \n"
 

Makefile.sp

@@ -139,8 +139,13 @@ sp-pdf: sp-pdf-prep
 	@rm -r $(BUILDDIR)/latex
 	@echo "\nOutput can be found in ./$(BUILDDIR)\n"
 
-sp-allmetrics:
-	@echo "Recording metrics..."
+sp-allmetrics: sp-install
+	@echo "Recording documentation metrics..."
+	@echo "Checking for existence of vale..."
+	. $(VENV)
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
+	@. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
+	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
 	@if [ ! -f '$(METRICSDIR)/metrics.yaml' ]; then touch $(METRICSDIR)/metrics.yaml; fi
 	@eval '$(METRICSDIR)/scripts/source_metrics.sh $(PWD)'
 	@eval '$(METRICSDIR)/scripts/build_metrics.sh $(PWD) $(METRICSDIR)'

metrics/metrics.yaml

@@ -1,7 +1,10 @@
 metrics:
-  wordcounttotal: 0
   filecount: 0
   linkcount: 0
   imagecount: 0
+  wordcountraw: 0
+  wordcounttotal: 0
+  wordcountaverage: 0
+  readability: 0.00
 tests:
   readable: true

metrics/scripts/build_metrics.sh

@@ -1,21 +1,20 @@
 #!/bin/bash
-mf="$2/metrics.yaml"
+
+METRICSFILE="$2/metrics.yaml"
 links=0
 images=0
 
-if [ $# -eq 0 ]; then 
-    # number of links
-    links=$(find . -name '*.html' -exec cat {} + | grep "<a " | wc -l)
-    # number of images
-    images=$(find . -name '*.html' -exec cat {} + | grep "<img " | wc -l)
-fi
+# count number of links
+links=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep "<a " | wc -l)
+# count number of images
+images=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep "<img " | wc -l)
 
 # summarise latest metrics
-echo "Summarising metrics data calculated..."
+echo "Summarising metrics for build files (.html)..."
 echo "links: $links"
 echo "images: $images"
 
 # update metrics file
-echo "Updating $mf with calculated data..."
-yq eval ".metrics .linkcount = $links" -i  $mf
-yq eval ".metrics .imagecount = $images" -i  $mf
+echo "Updating $METRICSFILE with calculated data..."
+yq eval ".metrics .linkcount = $links" -i  $METRICSFILE
+yq eval ".metrics .imagecount = $images" -i  $METRICSFILE

metrics/scripts/source_metrics.sh

@@ -1,57 +1,106 @@
 #!/bin/bash
 
-metricfile=$PWD/metrics/metrics.yaml
+VENV=".sphinx/venv/bin/activate"
+METRICSFILE=$PWD/metrics/metrics.yaml
+
 files=0
 words=0
 mean=0
 readabilityWords=0
 readabilitySentences=0
 readabilitySyllables=0
 readabilityAverage=0
+# FIXME: get pre metrics working
+#readabilityCode=0
 readable=true
 
-if [ $# -eq 0 ]; then 
-    # number of files
-    files=$(find . \( -name '*.md' -o -name '*.rst' \) | wc -l)
-    # number of words
-    words=$(find . \( -name '*.md' -o -name '*.rst' \) -exec cat {} + | wc -w)
-    # calculate mean 
-    meanval=$(( words / files))
-    # calculate readability
-
-    for file in *.md # TODO: need to handle .rst also
-    do
-	readabilityWords=`vale ls-metrics $file  | jq ".words"`
-	readabilitySentences=`vale ls-metrics $file  | jq ".sentences"`
-	readabilitySyllables=`vale ls-metrics $file  | jq ".syllables"`
+# initialise metric file each time metrics are calculated
+# FIXME: add codeblocks: 0 when pre metrics working
+cat > "$METRICSFILE" << EOF
+metrics:
+  filecount: 0
+  linkcount: 0
+  imagecount: 0
+  wordcountraw: 0
+  wordcounttotal: 0
+  wordcountaverage: 0
+  readability: 0.00
+tests:
+  readable: true
+EOF
+
+# measure number of files (.rst and .md), excluding those in .sphinx dir
+files=$(find . -type d -path './.sphinx' -prune -o -type f \( -name '*.md' -o -name '*.rst' \) -print | wc -l)
+
+# calculate metrics only if source files are present
+if [ "$files" -eq 0 ]; then
+    echo "There are no source files to calculate metrics"
+else
+    # measure raw total number of words, excluding those in .sphinx dir
+    words=$(find . -type d -path './.sphinx' -prune -o \( -name '*.md' -o -name '*.rst' \) -exec cat {} + | wc -w)
+
+    # calculate readability for markdown source files
+    echo "Activating virtual environment to run vale..."
+    source "${VENV}"
+
+    # NOTE: other Vale metrics to consider: "heading_*", "list", "pre"
+    for file in *.md *.rst; do
+        if [ -f "$file" ]; then
+                readabilityWords=$(vale ls-metrics $file | grep '"words"' | sed 's/[^0-9]*//g')
+                readabilitySentences=$(vale ls-metrics $file | grep '"sentences"' | sed 's/[^0-9]*//g')
+                readabilitySyllables=$(vale ls-metrics $file | grep '"syllables"' | sed 's/[^0-9]*//g')
+                # FIXME: get pre metrics working
+                # readabilityCode=$(vale ls-metrics $file | grep '"pre"' | sed 's/[^0-9]*//g')
+        fi
     done
 
+    echo "Deactivating virtual environment..."
+    deactivate
+
+    # calculate mean number of words
+    if [ "$files" -ge 1 ]; then
+        meanval=$(( readabilityWords / files))
+    else meanval=$readabilityWords
+    fi
+
     readabilityAverage=$(echo "scale=2; 0.39 * ($readabilityWords / $readabilitySentences) + (11.8 * ($readabilitySyllables / $readabilityWords)) - 15.59" | bc)
 
     # cast average to int for comparison
     readabilityAverageInt=$(echo "$readabilityAverage / 1" | bc)
 
+    echo "$readabilityAverageInt"
+
     # value below 8 is considered readable
     if [ "$readabilityAverageInt" -lt 8 ]; then
-	readable=true
+        readable=true
     else 
-	readable=false
+        readable=false
     fi
 
-fi
+    # summarise latest metrics
+    echo "Summarising metrics for source files (.md, .rst)..."
+    echo "total files: $files"
+    echo "total words (raw): $words"
+    echo "total words (prose): $readabilityWords"
+    echo "average word count: $meanval"
+    echo "readability: $readabilityAverage"
+    echo "readable: $readable"
+    # FIXME: get pre metrics working
+    # echo "code blocks: $readabilityCode"
+
 
-# summarise latest metrics
-echo "Summarising metrics data calculated..."
-echo "files: $files"
-echo "total: $words"
-echo "average: $meanval"
-echo "readability: $readabilityAverage"
-echo "readable: $readable"
-
-# update metrics file
-echo "Updating metrics.yaml with calculated data..."
-yq eval ".metrics .filecount = $files" -i  $metricfile
-#yq eval ".metrics .wordcounttotal = $words" -i  $metricfile
-#yq eval ".metrics .wordcountaverage = $meanval" -i  $metricfile
-yq eval ".metrics .readability = $readability" -i  $metricfile
-yq eval ".tests .readable = $readable" -i  $metricfile
+    # update metrics file
+    echo "Updating metrics.yaml with calculated data..."
+    yq eval ".metrics .filecount = $files" -i  $METRICSFILE
+    yq eval ".metrics .wordcountraw = $words" -i  $METRICSFILE
+    yq eval ".metrics .wordcounttotal = $readabilityWords" -i  $METRICSFILE
+    yq eval ".metrics .wordcountaverage = $meanval" -i  $METRICSFILE
+    yq eval ".metrics .readability = $readabilityAverage" -i  $METRICSFILE
+    yq eval ".tests .readable = $readable" -i  $METRICSFILE
+    # FIXME: get pre metrics working
+    # if [ -z "$readabilityCode" ]; then
+    #     yq eval ".metrics .codeblocks = 0" -i  $METRICSFILE
+    # else
+    #     yq eval ".metrics .codeblocks = $readabilityCode" -i  $METRICSFILE
+    # fi
+fi