hook-summary.py

#!/usr/bin/env python

import yaml
import re
from os.path import dirname, abspath, join

PROJECT_ROOT = dirname(dirname(abspath(__file__)))
DOCS_ROOT = join(PROJECT_ROOT, 'docs/')
MKDOCS_YAML_FILE = join(PROJECT_ROOT, 'mkdocs.yml')
OUTPUT_FILE = join(DOCS_ROOT, 'hooks/', 'list.md')
HEADER = """# All hooks

<!--
 -- DO NOT EDIT
 --
 -- This entire page is auto-generated by the following command:
 -- ./bin/hook-summary.py
 --
 -->


This is an overview list of all available hooks, listed by category.
"""

def findBetween( s, first, last ):
    start = s.index( first ) + len( first )
    end = s.index( last, start )
    return s[start:end]

def getSummary(hookFile):
    content = open(join(DOCS_ROOT + hookFile), 'r').read()
    summary = findBetween(content, '## Summary', '##')
    summary = re.sub('This hook (is)?(was)?', '', summary)
    summary = re.sub('\s+', ' ', summary).strip()
    if not (summary.endswith('.')):
      summary = summary + '.'
    return summary

output = f = open(OUTPUT_FILE, 'w')
with open(MKDOCS_YAML_FILE, 'r') as f:
    doc = yaml.load(f)
    pages = doc["pages"]
    for section in pages:
        if "Hooks" in section:
            hookSection = section.get("Hooks")

output.write(HEADER)

for section in hookSection:
    categoryHooks = list()
    category, hookList = section.popitem()
    if isinstance(hookList, list):
      for hookDetails in hookList:
          hookName =  hookDetails.iterkeys().next()
          if re.match("^(<del>)?hook_civicrm_*", hookName):
              categoryHooks.append(hookDetails)

    if len(categoryHooks) > 0:
        output.write('\n## {}\n\n'.format(category))
        for hookDetails in categoryHooks:
            hookName, hookFile = hookDetails.popitem()
            summary = getSummary(hookFile)
            output.write('* **[{}](/{})** - {}\n'.format(hookName, hookFile, summary))