DOC: Add more documentation showcasing CalendarDay
xref https://github.com/pandas-dev/pandas/pull/22288#issuecomment-419572535

Highlighting usages of `CalendarDay` with `date_range` and `resample` specifically.