GitLab

Created by: seancolsen

I'd like some feedback from others on how we should be aiming to document CiviCRM's regions.

The current situation

1. We have a Region Reference page with a bunch of good content about how regions work and how to use them.

   • There's also a section within that page which lists specific regions. That's what I'm talking about here.
   • That list of regions came over from the wiki where it appears to have been authored mostly by @totten and @eileenmcnaughton
   • In theory, I like the idea of maintaining a list of regions in the docs, but only if it's a complete list and if adds value beyond what a developer would find by grepping templates for {crmRegion.
   • Currently the list is incomplete. I can help complete it, but I'm not actually convinced it's worth it for us to maintain this.

2. In https://github.com/civicrm/civicrm-core/pull/11439 @tunbola added a new region a couple days ago.

   1. @colemanw merged this PR even though it lacked corresponding documentation. (Normally the missing doc would bother me, but in this case I'm kind of on the fence about whether it even should be documented.)
   2. Later, @tunbola reached out to me to ask where to add the appropriate docs, given that there is no "Contact" section in the list of regions. It really had me scratching my head.

Options for moving forward

• Flesh out the "List of Regions" documentation to mention the missing regions, including the newly added contact-page-inline-actions region.
• Or... Remove the list of specific regions altogether and replace it with generic instructions for finding regions by inspecting the codebase.

Finding undocumented regions

Just in case we do decide to keep the list, here's how we can make it complete. This bash snippet compares the codebase to the docs to spot missing regions.

civicrmDir="$HOME/buildkit/build/dmaster/sites/all/modules/civicrm"
devGuideDir="$HOME/civicrm/documentation/guides/dev"

regions=$(grep -Phiro '\{crmRegion((?!\}).)*\}' "$civicrmDir/templates" \
  | grep -Po '(?<=name=)((?!\s|\}).)*' \
  | sed -E 's/("|'"'"')//g' \
  | sort | uniq)

while read -r region; do
  if ! grep -q "$region" "$devGuideDir/docs/framework/region.md" ; then
    echo $region
  fi
done <<< "$regions"

Currently this gives:

billing-block-post
billing-block-pre
case-activity-form
contact-addresses
contact-basic-info-left
contact-basic-info-right
contact-comm-pref
contact-demographic
contact-details-left
contact-details-right
contact-page-inline-actions
contribute-form-contributionpage-addproduct-main
contribution-soft-credit-block
crm-activity-userdashboard-post
custom-data-view-`$cd_edit.name`
$customRegion
onbehalf-block
payment-edit-block
payment-info-block
profile-form-`$ufGroupName`
profile-search-`$ufGroupName`
profile-view-`$ufGroupName`
$region

Some of those are actually already documented, like contribute-form-contributionpage-addproduct-main which is misspelled in the docs, or ``profile-form-$ufGroupName``` which is documented as profile-form-(NAME)`. But most of that list above represents missing doc.