docs: Fix highlighting in examples

[jmgate]

Type: Documentation

Description

I never noticed when we added the license and copyright information to the top of all the source files that we didn't account for the lines highlighted in the included examples. This adjusts things such that (1) we don't include all that header stuff when generating the docs, and only include the lines of code that are really relevant to share on the examples page, and (2) the appropriate lines are highlighted.

Related Issues/PRs

Closes #194.

Motivation

We need the docs to be accurate so potential new users don't get confused when coming up to speed.

Screenshots/Recordings

Before:

After::

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 94.04%. Comparing base (04cf2cc) to head (149e48c).
Report is 89 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #195   +/-   ##
=======================================
  Coverage   94.04%   94.04%           
=======================================
  Files           2        2           
  Lines         168      168           
  Branches       43       43           
=======================================
  Hits          158      158           
  Misses          4        4           
  Partials        6        6           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jmgate]

@william76, you want to give this a quick once-over and approve? Just ensure the highlighting in all the built examples looks right to you.

[jmgate]

@GhostofGoes, you mind giving this a quick review and approval?

[GhostofGoes]

LGTM. In the future, you could use comments as markers for start/end, instead of manually specifying lines.

[jmgate]

That sounds spiffy. Can you give me an example of what that looks like?

[GhostofGoes]

That sounds spiffy. Can you give me an example of what that looks like?

That sounds spiffy. Can you give me an example of what that looks like?

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude

"Another way to control which part of the file is included is to use the start-after and end-before options (or only one of them). If start-after is given as a string option, only lines that follow the first line containing that string are included. If end-before is given as a string option, only lines that precede the first lines containing that string are included. The start-at and end-at options behave in a similar way, but the lines containing the matched string are included.

start-after/start-at and end-before/end-at can have same string. start-after/start-at filter lines before the line that contains option string (start-at will keep the line). Then end-before/end-at filter lines after the line that contains option string (end-at will keep the line and end-before skip the first line)."

I don't have an example that can be shared publicly unfortunately.

[jmgate]

Holy cow—why didn't I see that before? I'll file an issue to make that change on a rainy day. Thanks so much 😃