Exploratory tutorial conversion to use example directory

[skalish]

↪️ Pull Request

This PR converts the get_version tutorial from Markdown to reST in order to source all code-blocks from the script tamr_client/examples/get_tamr_version.py, which is included in the CI tasks.

This is mostly intended to illustrate how documentation that displays code from examples, as discussed in #450.

✔️ PR Todo

• [x] Added/updated testing for this change
• [x] Included links to related issues/PRs
• [x] Update relevant docs + docstrings
• [x] Update the CHANGELOG under the current -dev version:
  • Add changelog entries under any that apply: BREAKING CHANGES, NEW FEATURES, BUG FIXES.
  • Changelog entry format: [#<issue number>](<link to issue>) <change description>

[skalish]

For a PR regarding docs, is there a good way of including some form of the built docs pages relevant to the PR? It doesn't look like html can be uploaded, and pdf print-outs of the webpage don't really represent the real thing well.

[pcattori]

For a PR regarding docs, is there a good way of including some form of the built docs pages relevant to the PR? It doesn't look like html can be uploaded, and pdf print-outs of the webpage don't really represent the real thing well.

@skalish : do you mean so that reviewers can see what the visual changes are? If so, I think screenshots of the locally built docs are fine.

[pcattori]

@skalish if you add CI for linting/formatting/typechecking the examples, we can close #450 with this PR

[skalish]

@skalish if you add CI for linting/formatting/typechecking the examples, we can close #450 with this PR

@pcattori One way I see of doing this is just adding an empty __init__.py file into the tamr_client/examples directory. The lint/format/typecheck nox tasks then automatically check the contents of the directory. Does this seem like the best way to handle this? Do we maybe want examples to be outside of tamr_client alongside tests, etc.?

[pcattori]

@skalish if you add CI for linting/formatting/typechecking the examples, we can close #450 with this PR

@pcattori One way I see of doing this is just adding an empty __init__.py file into the tamr_client/examples directory. The lint/format/typecheck nox tasks then automatically check the contents of the directory. Does this seem like the best way to handle this? Do we maybe want examples to be outside of tamr_client alongside tests, etc.?

@skalish : Including the empty __init__.py is fine, but could you add a comment within it explaining why it's there (e.g. "This empty __init__.py file is necessary for lint, format, and typechecking tasks to run on the included examples")?

I think having examples/ as a sibling of docs/ and tests/ would be better. (not sure if the __init__.py will be necessary if its placed there)

[skalish]

@skalish if you add CI for linting/formatting/typechecking the examples, we can close #450 with this PR

@pcattori One way I see of doing this is just adding an empty __init__.py file into the tamr_client/examples directory. The lint/format/typecheck nox tasks then automatically check the contents of the directory. Does this seem like the best way to handle this? Do we maybe want examples to be outside of tamr_client alongside tests, etc.?

@skalish : Including the empty __init__.py is fine, but could you add a comment within it explaining why it's there (e.g. "This empty __init__.py file is necessary for lint, format, and typechecking tasks to run on the included examples")?

I think having examples/ as a sibling of docs/ and tests/ would be better. (not sure if the __init__.py will be necessary if its placed there)

Agreed. lint and format are "opt-out" so they still pick up a sibling examples, and the change to typechecking is pretty simple.