Show example references to API documentation

[cmarqu]

I noticed that no roles are used that point to API documentation, like
:py:func: `myfunction`.

#157 fixes that, but only very indirectly. I think an example for API references should be added elsewhere too.

[stevepiercy]

We'd need to document that folks must enable and configure Intersphinx for the Python domain, else it renders as plain text instead of a link. See #182 (review)