We can use python to generate a readability score for our documents. We may want to do this to all our documentation from time to time to improve document quality.

The below example gives us a single ARI score for a Sphinx document. We could also recursively apply this for all our documents at once if we want or add it to our DevOps for documentation pipeline.


  # prerequisites: Sphinx and pandoc and below listed python libraries
  from readability import Readability
  from bs4 import BeautifulSoup
  import os

  os.system("sphinx-build -b singlehtml . _build/singlehtml") # Runs sphinx and builds a single html file of all content.
  file = open('_build/singlehtml/index.html',mode='r',encoding='utf8') # Opens the output file with utf8 encoding
  soup = BeautifulSoup(file, 'html5lib') # Cleans the markdown html file

  for h1 in soup("h1"): # Removes all h1 elements, add other elements as needed

  r = Readability(soup.text) # Processes readability on cleaned text
  f = r.ari() # Runs ARI algorithm on readability
  print(f.score) # Prints out the ARI score